Skip to main content

Boas Práticas

Histórico de Versões​

VersãoAutorDataAlteração
1.4Tássio Auad10/07/2023Adicionada a proibição do Identificador do cliente em APIs. Obrigatoriedade do padrão RESTful nas APIs.
1.3Tássio Auad26/05/2023Identificador da tarefa no Jira nos commits.
1.2Tássio Auad11/04/2023Criado itens de revisão do Frontend.
1.1Tássio Auad29/03/2023Cuidados com console.log. Separação de itens Gerais, Backend e Frontend.
1.0Tássio Auad09/03/2023Versão inicial com verificações para projetos backend.

1. Geral​

1.1 Estilo de Código​

Língua Inglesa​

  • Todo o código deve ser escrito na língua inglesa, se adequando às palavras reservadas da própria linguagem de programação.

Indentação​

  • O código deve ser indentado com quatro espaços em branco e não com tabulação.

Nomenclatura​

  • Utilize nomes descritivos e claros para variáveis, funções, classes e outros elementos do código.
  • Evite abreviações desnecessárias e nomes confusos que não transmitam o significado real da função.

Nomes descritivos​

  • Use nomes descritivos e claros para variáveis, métodos e classes.
  • Os nomes devem indicar claramente a finalidade e a função da variável, método ou classe.

Exemplo:

// Nome descritivo (bom)
const userFullName = "Tássio Auad";

// Nome não descritivo (ruim)
const x = "Tássio Auad";

Estilo​

  • Utilize CamelCase para nomes de classes, métodos e variáveis.
  • Utilize snake_case para atributos no JSON e no banco de dados (colunas e tabelas).
  • Utilize kebab-case (também chamado de spinal-case) para nomes de pastas e arquivos do projeto, onde todas as palavras são minúsculas e separadas por -.

Evite abreviações desnecessárias​

  • Prefira nomes completos e claros sempre que possível.
  • Evite abreviações que dificultem a compreensão do código.

Exemplo:

// Nome completo (bom)
const userFullName = "Tássio Auad";

// Abreviação desnecessária (ruim)
const userFn = "Tássio Auad";

Evite nomes genéricos​

  • Evite nomes genéricos como "data" ou "temp", pois eles não deixam claro o propósito da variável.
  • Prefira nomes mais descritivos e específicos que indiquem claramente sua finalidade.

Exemplo:

// Nome específico (bom)
const userCreatedAt = new Date();

// Nome genérico (ruim)
const date = new Date();

Comentários​

  • O código deve estar bem documentado com comentários que ajudem outros desenvolvedores a entender o código.
  • Comentários desnecessários ou que não contribuem para a compreensão do código devem ser evitados.

Linhas Vazias​

  • Use linhas vazias para separar blocos de código relacionados, como funções ou condicionais.
  • Isso ajuda a tornar o código mais legível.

Limites de Linha​

  • Evite linhas muito longas.
  • As linhas não devem ter mais de 120 caracteres.
  • Se uma linha ficar muito longa, quebre-a em várias linhas.

Clareza​

  • Escreva o código de forma clara e concisa.
  • Evite código confuso, excessivamente complexo ou difícil de entender.
  • Use funções bem nomeadas e crie comentários explicativos para ajudar na compreensão.

Declaração de Variáveis​

  • Declare variáveis no início da função ou bloco de código, antes de usá-las.
  • Isso ajuda a manter o código organizado e legível.

Espaços em Branco​

  • Use espaços em branco para separar elementos do código, como operadores matemáticos ou argumentos de função.
  • Use um espaço antes e depois de operadores e depois de vírgulas em listas de argumentos de função.

Linter​

  • Use um linter, como o ESLint, para ajudar a garantir que o código siga as diretrizes de estilo e sintaxe.

Reutilização de Código​

  • Evite duplicação de código.
  • Use funções e módulos reutilizáveis em vez de duplicar o mesmo código várias vezes.

Manipulação de Erro​

  • Certifique-se de que o código manipule erros de forma apropriada.
  • Isso inclui lançar erros quando algo der errado e capturar erros para que o programa não pare de funcionar inesperadamente.

1.2 Segurança e Testes​

Versão fixa das bibliotecas​

  • Mantenha as versões fixas e definidas das bibliotecas, evitando margem para updates automáticos.

Validação de entrada de dados​

  • Verifique se todas as entradas de dados fornecidas pelos usuários são validadas e sanitizadas adequadamente.
  • Isso ajuda a evitar vulnerabilidades como XSS (Cross-site Scripting) e SQL Injection.

Proteção contra ataques de XSS​

  • Verifique se o código é protegido contra ataques de XSS, garantindo que as entradas do usuário sejam adequadamente sanitizadas e validadas antes de serem processadas.

Proteção contra ataques de CSRF​

  • Verifique se o código é protegido contra ataques de CSRF.
  • Use tokens de validação, validação de referência e outras técnicas para verificar a autenticidade das solicitações.

Autenticação e autorização​

  • Verifique se o código implementa a autenticação e autorização adequadamente, para proteger áreas restritas e garantir que os usuários tenham acesso somente aos recursos que lhes são permitidos.

Cliente ligado ao Usuário​

  • Verifique se existe a possibilidade de forçar o identificador de um cliente não relacionado ao usuário do token.

Proteção de dados sensíveis​

  • Verifique se as informações confidenciais, como senhas e informações de cartão de crédito, são protegidas adequadamente.
  • Utilize criptografia e outras medidas de segurança para proteger esses dados.

Gerenciamento de sessão e cookies​

  • Verifique se o código gerencia as sessões dos usuários adequadamente, com cookies seguros, validação de sessão e outras técnicas para proteger contra ataques de sessão.

Use cookies seguros​

  • Certifique-se de que os cookies sejam enviados somente por meio de conexões HTTPS.
  • Isso garante que os cookies não possam ser interceptados ou modificados por atacantes.

Use cookies HTTP-only​

  • Certifique-se de que os cookies sejam definidos como HTTP-only.
  • Isso impede que scripts do lado do cliente acessem o conteúdo dos cookies, reduzindo o risco de ataques de XSS.

Defina a expiração dos cookies​

  • Defina uma data de expiração para os cookies, para que eles sejam excluídos automaticamente após um determinado período de tempo.
  • Isso reduz o risco de cookies permanentes serem usados para rastrear a atividade do usuário.

Use nomes significativos para cookies​

  • Use nomes significativos para os cookies, para que sejam fáceis de identificar e rastrear.
  • Isso também ajuda a evitar conflitos com outros cookies que possam estar sendo usados no mesmo domínio.

Limite o tamanho dos cookies​

  • Limite o tamanho dos cookies para garantir que não sejam excessivamente grandes e que não afetem o desempenho do site.
  • Isso também reduz o risco de os cookies serem usados para armazenar informações sensíveis.

Use cookies somente quando necessário​

  • Use cookies somente quando necessário e evite armazenar informações confidenciais ou pessoais em cookies.
  • Em vez disso, armazene essas informações em um banco de dados seguro e use tokens de autenticação para validar as solicitações do usuário.

Exclua cookies desnecessários regularmente​

  • Exclua cookies desnecessários para garantir que não sobrecarreguem o navegador do usuário ou possam ser usados para rastrear a atividade do usuário.
  • Isso também ajuda a manter o desempenho do site e a privacidade do usuário.

Prevenção de injeção de código​

  • Verifique se o código está protegido contra vulnerabilidades de injeção de código, como SQL Injection e Injection de comando.

Validar entradas do usuário​

  • Certifique-se de que todas as entradas do usuário sejam validadas e sanitizadas adequadamente.
  • Isso inclui validação de formulários, dados recebidos de APIs e outras fontes de entrada de dados.

Use Prepared Statements para consultas SQL​

  • Ao trabalhar com bancos de dados, use Prepared Statements ou Stored Procedures para evitar vulnerabilidades como SQL Injection.

Evite a concatenação de strings em consultas SQL​

  • Evite a concatenação de strings para gerar consultas SQL, pois isso pode expor o aplicativo a vulnerabilidades como SQL Injection.

Utilização do Identificador do Cliente​

  • Evite receber o identificador do cliente como parâmetros de qualquer tipo nas APIs do software.
  • Caso seja necessário descobrir o identificador do cliente em um procedimento de uma API, extraia-o do token de autenticação recebido.

Use CORS para restringir o acesso aos recursos​

  • Use a política Same Origin e o CORS para restringir o acesso aos recursos do seu aplicativo.
  • Isso evita que atacantes acessem seus recursos de outros domínios.

Adição de bibliotecas​

  • Bibliotecas só podem ser adicionadas aos projetos com autorização do Líder da Squad ou Gerente de Tecnologia.
  • Toda nova biblioteca precisa ser avaliada sob critérios definidos pela Gerência de Tecnologia.

Tratamento de exceções​

  • Verifique se o código trata exceções adequadamente e evita falhas do sistema.
  • Os erros devem ser capturados de forma adequada e tratados de acordo com o problema.

Exposição de erros​

  • Verifique se durante o tratamento de erros é evitado que informações sensíveis sejam expostas a usuários mal-intencionados.

Teste unitário​

  • Todo código acrescentado deve ser acompanhado por testes unitários que façam cobertura de pelo menos 80%.

Teste de penetração​

  • Realize testes de penetração regulares para identificar possíveis vulnerabilidades de segurança na tarefa.
  • O relatório deve ser entregue junto do checklist.

console.log​

  • Verifique se há algum comando de exibição de logs que esteja projetando informação sensível sobre o projeto para algum local inadequado, como o próprio navegador.
  • Remova todos os comandos console.log, pois todos os logs devem ser transmitidos via framework adequado a um repositório seguro.

1.3 Commits​

Padrão do commit​

  • Todo commit deve ser formado por um título e uma descrição.
  • Todo título do commit deve conter um identificador da tarefa no Jira e um identificador de tipo, onde:
    • feat significa funcionalidade
    • fix significa correção
    • refact significa refatoração

Exemplo:

feat(NXS-9999): Adição de escuta do tópico /analysis do RabbitMQ

Foi adicionada uma escuta do tópico /analysis do RabbitMQ no serviço de preparo de
texto do chat para realização de análise de sentimentos.

Língua do Commit​

Todo commit deve utilizar em seu título e descrição a língua portuguesa.

Baby Steps Commit​

É atribuição do desenvolvedor dividir a tarefa em etapas de acordo com seu ponto de vista e personalidade.
A divisão em etapas deve refletir no fluxo de commits, onde cada commit simboliza a conclusão de uma etapa, que pode ser:

  • Refatoração
  • Adição de funcionalidade
  • Correção

Merge no Fast-Forward​

Toda unificação de branches deve utilizar o merge do tipo fast-forward.
Caso haja necessidade de outro tipo de merge, deve-se solicitar autorização do Líder da Squad ou Gerente de Tecnologia.

git merge –no-ff <branch>

1.4 Outros​

Adequação aos Requisitos​

Verifique se todo o código acrescentado está adequado ao que foi estipulado pelo documento de requisitos.

Não Reinventar a Roda​

Garanta que o código não esteja reinventando a roda, mas sim utilizando bibliotecas e frameworks existentes sempre que possível.
Isso ajuda a:

  • Economizar tempo
  • Evitar problemas de segurança
  • Garantir compatibilidade com outras partes do sistema

2. Projetos Frontend​

2.1 Usabilidade​

Quebra de Estilo​

  • O CSS está coerente com o que foi passado e não há quebras no estilo.

2.2 Estilo de Código​

Desabilitar Regras​

  • Evitar desabilitar regras do Lint sem uma justificativa válida.
  • Se for necessário, documente o motivo da desativação.

CSS Inline​

  • Evite o uso de CSS inline se houver mais de três elementos estilizados.

Enums Reutilizáveis​

  • Não crie enums que não sejam reutilizáveis.
  • Utilize props no Styled Component quando necessário.

Reutilização de Enums​

  • Sempre reutilize enums já existentes para nome, cor e ícones de canais.

Localização dos Enums​

  • Enums reutilizáveis devem ser criados na pasta Enums.

onClick​

  • O código dentro do onClick não deve ultrapassar 3 linhas.
  • Caso ultrapasse, crie uma função separada com um nome descritivo para representar a ação.

Nome dos Componentes​

  • Utilize nomes descritivos para variáveis, funções e componentes.
  • Evite abreviações ou nomes genéricos.

Linhas Extensas​

  • Evite linhas muito longas no código.
  • Faça quebras para manter a legibilidade e manutenção do código.

2.3 Outros​

Variáveis e Funções Não Utilizadas​

  • Remova variáveis e funções que não estão sendo utilizadas no código.

3. Projetos Backend​

3.1 Estilo de Código​

Serviços e APIs​

  • Evite incluir regras de negócio ou orquestrações diretamente no código das APIs e serviços.
  • Componentize o projeto para garantir reutilização e flexibilidade na arquitetura.

Padrão RESTful em APIs​

  • Todas as APIs devem seguir o padrão RESTful, garantindo uma estrutura clara e consistente.
  • Utilize os verbos HTTP corretamente:
    • GET → Buscar informações
    • POST → Criar um novo recurso
    • PUT → Atualizar um recurso existente
    • DELETE → Remover um recurso

Organização de Componentes​

  • Componentes devem ser organizados em pastas com nomes claros e descritivos.
  • Arquivos relacionados devem ser agrupados em pastas ou subpastas.

Estrutura Mínima de Pastas​

  • data
  • entity
  • test
  • arquivo-principal.js

3.2 Integrações​

Conexões com o Banco de Dados​

  • Fechamento de Conexões: Certifique-se de que todas as conexões abertas com o banco de dados são corretamente fechadas após o uso.
  • Reutilização de Conexões: Utilize um pool de conexões para otimizar o uso do banco de dados e evitar desperdício de recursos.

Armazenamento Adequado de Logs​

  • Identificar se os logs estão sendo corretamente enviados para a New Relic.

Healthcheck​

  • Identificar que o healthcheck contém verificação de todas as integrações.

Alertas de Falha​

  • Identificar se os alertas de healthcheck estão chegando ao canal destino no Slack.

3.3 Outros​

Uso de const e let​

  • Verifique se o código usa const e let em vez de var para declarar variáveis. Isso ajuda a evitar problemas de escopo e torna o código mais seguro.

Evite Global Variables​

  • Verifique se o código evita variáveis globais e usa módulos para encapsular o código. Isso ajuda a evitar conflitos de nomes e torna o código mais modular e reutilizável.

Não Usar eval()​

  • Verifique se o código não usa a função eval() para executar código dinamicamente, pois isso pode ser uma fonte de vulnerabilidades.

Instanciação de Dependências​

  • Verifique se todas as dependências de uma classe estão sendo recebidas como parâmetro no construtor em vez de serem instâncias diretamente, seja no construtor ou fora dela.