Sua alma na documentação - DocSoul

Em minha concepção, é necessário entender que ter “boas práticas” não é como aprender uma nova linguagem e sim aplicar uma vertente de lógica visando um entendimento e manutenção futura de um código.

O mais comum é quando um desenvolvedor precisa alterar uma aplicação que não foi codificada com “boas práticas”, sendo necessário muitas vezes, refatorar e perder tempo com coisas que deveriam ser muito mais simples.

Outra situação, é quando um desenvolvedor tem um projeto em desenvolvimento e decide parar a codificação para continuar futuramente.

Se este desenvolvedor fez seu código utilizando boas práticas e até mesmo fazendo DocSoul, terá um ganho de tempo, simplificando e agilizando seu trabalho.

Nomenclatura de variáveis

É muito importante que você deixe que uma variável seja auto explicativa, ou seja, quando um Dev se deparar com ela, ele saberá exatamente o propósito da mesma.

Por exemplo, ao invés de utilizar:

let d
let elapsed
const ages = arr.map((i) => i.age)

Utilize:

let daysSinceModification
const agesOfUsers = users.map((user) => user.age)

Jamais pense em usar:

let nameString
let theUsers

Quando somente o necessário é o melhor:

let name
let users

Funções

Uma função tem o propósito de nomenclatura muito semelhante ao de uma variável, portanto, deixe sua função nomeada de forma com que o desenvolvedor, ao acessar, saiba exatamente sua finalidade.

Por exemplo, imagine que temos uma função que convida um usuário, utilizando seu e-mail. Nesse caso, poderíamos fazer desta forma (uma das formas mais comuns):

function conv (usuario) { }

Basicamente, a abreviação ‘conv’ no nome da função acima significa ‘convidar’ e o parâmetro é chamado de ‘usuário’ pois identificará este por meio de seu email.
Porém, o ideal seria fazer:

function convidarUsuario (email) { }

Desta maneira, a função tem um nome claro independente de onde for chamada!

Ter boas práticas é somente o primeiro passo para ter organização, qualidade e eficiência em seus projetos. O ideal é conciliar com DocSoul, que vai além das boas práticas, é uma cultura a ser desenvolvida e incentivada, tanto por desenvolvedores quanto pela empresa, deixando sua marca no documento, para que quando um desenvolvedor visualize seu código, além de entender a lógica e suas tomadas de decisões, reconheça e entenda que além da linha de raciocínio desenvolvida para aquele código, tem sua marca registrada.

Valeu pessoal!