Nos últimos cinco anos, tenho tentado constantemente melhorar minhas habilidades de codificação, e uma delas foi aprender e seguir os estilos de codificação mais recomendados.
Este guia tem como objetivo ajudá-lo a escrever código consistente e elegante e inclui alguns conselhos para melhorar a legibilidade e a manutenção do código. Ele é inspirado nas diretrizes populares mais aceitas na comunidade, mas tem algumas modificações para se adequar mais às minhas preferências.
Vale ressaltar que sou um desenvolvedor JavaScript full-stack e todas as minhas anotações são específicas para minha stack tecnológica (MEVN) e podem não ser aplicáveis ​​a outras stacks.

Regras Gerais

Evite duplicação de código

Se houver necessidade de escrever o mesmo bloco de código (ou com algumas diferenças gerenciáveis) em mais de um lugar, é essencial fundi-los em uma função e, daqui em diante, chamar a função sempre que necessário.

Considere acoplamento solto

As funções devem funcionar de forma independente, o que significa que a edição de uma deve ter absolutamente nenhum efeito nas outras, desde que a entrada e as saídas permaneçam as mesmas. Cada função não deve ter nenhum conhecimento das definições das outras e funcionar como um componente separado. Nessa situação, tudo o que ele conhece são seus parâmetros, e não importa quem chame a função, as mesmas entradas sempre retornam os mesmos resultados.

Declaração

Em primeiro lugar, lembre-se de declarar as variáveis ​​o tempo todo.
Use a palavra-chave const quando uma variável não for reatribuída. No entanto, você ainda pode usar const para variáveis ​​que são objetos ou matrizes, mesmo se você planeja reatribuir seus elementos aninhados.
Observe que é necessário exigir módulos e definir variáveis ​​constantes sempre usando a palavra-chave const.
Use a palavra-chave let quando não puder usar const e use a palavra-chave var apenas se precisar oferecer suporte a navegadores mais antigos.

Funções

As funções devem ser limitadas ao seguinte:

• Quatro variáveis
• Quatro parâmetros
• Trinta linhas de código (ignorando comentários)
• Quatro ramificações (if-else, while, for, or-and, switch-case)

As linhas de código devem ser limitadas a 100 caracteres e, para agrupar/organizar as funções, é melhor manter as funções relacionadas o mais próximas possível.
Privilegie a sintaxe da função de seta para a alternativa tradicional sempre que possível.

Cordas

Use aspas simples ' (em vez de aspas duplas ") para literais de string comuns, mas para strings com variáveis/expressões incorporadas, strings de múltiplas linhas e strings que contêm caracteres de aspas simples, use literais de modelo.

Nomeação

É essencial manter a consistência ao nomear variáveis. Isso significa que se variáveis ​​em páginas diferentes forem responsáveis ​​pelos mesmos dados, elas deverão ter o mesmo nome.

Os nomes de variáveis, funções, métodos e parâmetros devem ser autodescritivos, o que significa que qualquer pessoa deve ser capaz de saber (ou pelo menos fazer um palpite justo) sobre os dados contidos apenas olhando seus nomes.

Variáveis ​​constantes devem estar em letras maiúsculas, com palavras separadas por sublinhados. Funções, variáveis ​​e métodos devem seguir a sintaxe camelCase, enquanto classes CSS e ids devem seguir a sintaxe kebab-case.

Comentários

Os comentários devem sempre começar com letra maiúscula e ser limitados a 100 caracteres. Você deve se lembrar que as linhas de código seguiriam a mesma regra, mas observe que se as linhas incluírem ambas, elas só poderão exceder 150 caracteres.
Comentários descrevendo as funções não devem ser escritos onde são chamadas, mas onde são definidas.

Coloque os comentários após os códigos de uma linha, a menos que o comprimento da linha exceda 150 caracteres. Nesses casos, e para códigos multilinhas, coloque os comentários no topo.

Em relação às instruções if, os comentários devem ser colocados após as instruções condicionais.

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

Lembre-se de usar barras duplas // para comentários de uma linha e /* */ para comentários de várias linhas. Ao adicionar comentários de várias linhas a códigos de uma linha ou instruções condicionais, coloque-os dentro de /* */ para que /* seja escrito na frente do código, o comentário comece na linha seguinte e */ seja escrito em uma nova linha. linha.

if (conditionIsTrue) { /*
        Put your comment here
        Put your comment here
    */
    doSomeThing();
}

functionName(parameter), /*
    Put your comment here
    Put your comment here
*/

Comentários descritivos da função

Coloque os comentários no topo das funções envolvidas por /** */.

• Descreva os parâmetros usando @param {type} variávelName description.
• Se o parâmetro puder aceitar mais de um tipo de variável, use @param {type1 | type2} descrição do nome da variável.
• Se o parâmetro for opcional e puder estar ausente, use @param {type} [variableName] descrição.
• Se o parâmetro tiver um valor padrão (deve ser opcional para poder ter um valor padrão de fato), use @param {type} [variableName="value"] descrição.
• Descreva a saída da função usando a descrição @returns {type}.

/**
 * Describing the function here
 * @param {type} normalVariable A normal variable
 * @param {type1 | type2} multiTypeVariable A variable with multiple expected types
 * @param {type} [variableWithDefaultValue="value"] An optional variable that has a default value in case of being absent when calling the function 
 * @param {type} [optionalVariable] An optional variable
 * @returns {type} description
*/
const functionName = (normalVariable, multiTypeVariable, variableWithDefaultValue, optionalVariable) => {
    doSomeThing();
}

Em relação às funções do servidor com parâmetros req e res, não há necessidade de descrever os parâmetros de solicitação; descreva apenas a resposta usando a descrição @returns.

/**
 * Describing the function here
 * @returns description
 */
functionName = (req, res) => {
    doSomeThing();
}

Geralmente, não há necessidade de descrever os parâmetros req, res, next, to e from.

Em arquivos HTML, use para separar diferentes partes do código; portanto, o usuário pode identificar cada parte facilmente.

Caso você escreva comentários no meio de uma linha de código, use /* */.

const calc_result = (firstNumber * secondNumber)/* Explain the reason for the multiplication */   thirdNumber;

Recuo

Espaços em branco à direita são proibidos.
Lembre-se de sempre colocar espaços ao redor de expressões, operadores e símbolos, e também depois de vírgulas e chaves, se eles não forem os últimos caracteres da linha.
Linhas vazias só são permitidas (e obrigatórias) no final do arquivo (todos os arquivos devem terminar em uma linha vazia), após o último módulo importado, separando as tags Template, Script e Style, e entre conjuntos de regras CSS.
Lembre-se de usar Tab para recuo e Espaço para alinhamento.

Ordem

• Ordene as variáveis ​​dos esquemas mongoose e o estado reativo Vue dos componentes em ordem alfabética, mas no resto do tempo ordene as linhas da mais curta para a mais longa.
• Ordene os métodos de rota na ordem put, get, post e delete, enquanto cada um está em ordem alfabética, e todas as rotas devem ser agrupadas com base em seus URLs.

Conclusão

Embora obviamente esses não sejam os melhores conselhos de todos os tempos, acredito que eles oferecem um ponto de partida sólido para qualquer pessoa interessada em aprender princípios de código limpo.
Além disso, embora o cumprimento estrito destas regras possa inicialmente parecer um desafio, torna-se muito mais simples com a prática.

É essencial enfatizar a necessidade de seguir as diretrizes do projeto atual ao trabalhar em uma base de código de longo prazo, mesmo que sejam insuficientes. Se você realmente quer revisar as diretrizes do projeto, considere as modificações mais benéficas e deixe-as serem injetadas no projeto gradualmente.

Crédito da imagem da capa: Foto de luis gomes da Pexels