Melhores práticas de padrão de código

Sumário

• Introdução
• Boas práticas gerais
• Boas práticas de git
• Boas práticas de banco de dados
• Boas práticas do back-end (Restful API)
• Boas práticas do front-end
  • Boas práticas de estilização

Introdução

Neste documento, você encontrará as melhores práticas de padrão de código que foram definidas para o projeto AGES. O objetivo deste documento é definir um padrão de código que deve ser seguido por todos os membros da AGES. Um padrão de código é um conjunto de regras que define como o código deve ser escrito. O padrão de código permite que os desenvolvedores escrevam código de maneira consistente e legível. O padrão de código também permite que os desenvolvedores mantenham o código de maneira fácil e eficiente. O padrão de código foi definido para o projeto AGES, mas pode ser usado e adaptado em qualquer projeto de software.

Boas práticas gerais

• Utilize nomes de métodos e variáveis em inglês.
• Utilize nomes de métodos no infinitivo.
• Utilize nomes de variáveis no formato: nomeDaVariavel.
• Utilize nomes de constantes no formato: NOME_DA_CONSTANTE.
• Utilize nomes de rotas no formato: /nomeDaRota.
• Utilize o padrão DTO (Data Transfer Object) para transferir dados entre o back-end e o front-end.
• Escreva arquivos e funções pequenas, isto é, cada arquivo e função deve ter apenas uma responsabilidade.
• Pense em como o código pode ser reutilizado.
• Não repita código.
• Não deixe nenhum comentário no código, apesar de ajudar durante o desenvolvimento, é considerado uma má pratica manter comentários em códigos disponibilizados pela AGES.

Boas práticas de git

• As descrições de tarefas mencionadas nos próximos items foram escritas em português.
• Utilize um padrão para os nomes de branches e commits, com o objetivo de facilitar a leitura e entendimento das branches e commits no gitlab.
• Tenha definido três categorias de branch:
  • 1: main --> a main deve ser preservada apenas para a versão estável do programa
  • 2: develop --> branch direcionada para o merge de todas as branches de categoria 3, onde será testado a integração das branches, e a criação das versões finais do projeto para cada sprint.
  • 3: Padrão de branch utilizado no projeto:
    • nome padrão para branches de features: feature/US-NúmeroDaUS-DescriçãoDaUS
    • nome padrão para branches de fix: fix/US-NúmeroDaUS-DescriçãoDaUS
    • nome padrão para branches que não contém US: NOUS/DescriçãoDaTarefa
• Para a mensagem de commit, descreva brevemente o que foi feito dentro dele, mantendo um padrão de escrita em português.

Boas práticas de banco de dados

• Use nomes de tabelas em inglês no plural.
• Use nomes de colunas em inglês no plural.
• Use nomes de chaves estrangeiras no formato: tabelaId.
• Utilize os tipos de dados corretos para cada coluna. Por exemplo, ao invés de armazenar tudo como VARCHAR, utilize
  • INT para números inteiros
  • FLOAT para números decimais
  • DATE para datas
  • TIME para horários
  • DATETIME para datas e horários
  • BOOLEAN para valores booleanos
• Utilize NOT NULL para colunas que não podem ser nulas.
• Utilize UNIQUE para colunas que não podem ter valores duplicados.
• Se possível, utilize um valor padrão para colunas que podem ser nulas.

Apesar de não ser necessário, utilizar um ORM (Object-Relational Mapping) pode facilitar o desenvolvimento e manutenção do banco de dados. Isso porque o ORM permite que o desenvolvedor utilize uma linguagem de programação para manipular o banco de dados, ao invés de utilizar SQL, e melhora a segurança, eficiência e portabilidade do banco de dados. Ainda, o ORM permite que o desenvolvedor utilize o banco de dados sem ter que se preocupar com a linguagem de programação utilizada no projeto e linguagem do banco de dados.

Boas práticas do back-end (Restful API)

• Armazene variáveis de ambiente em um arquivo .env.
• Utilize nomes de métodos e variáveis em inglês.
• Utilize nomes de métodos no infinitivo.
• Utilize nomes de variáveis no formato: nomeDaVariavel.
• Utilize nomes de constantes no formato: NOME_DA_CONSTANTE.
• Utilize nomes de rotas no formato: /nomeDaRota.
• Utilize uma pasta para cada recurso, isto é, dentro da pasta src/users, crie o arquivo user.controller e user.service.
• Faça a validação dos dados recebidos na requisição antes de processá-los.
• Utilize o padrão DTO (Data Transfer Object) para transferir dados entre o back-end e o front-end.

Boas práticas do front-end

• Utilize alguma biblioteca de componentes, como Material UI por exemplo.
  • Utilize os componentes da biblioteca de componentes sempre que possível.
  • Caso não seja possível utilizar os componentes da biblioteca de componentes, crie componentes reutilizáveis.
    • Crie componentes para cada elemento que se repete em mais de uma página.
    • Parametrize os componentes para que eles possam ser reutilizados em diferentes contextos.
• Utilize de ferramentas que padronizam o código para a equipe automaticamente:
  • Prettier, para a estilização do código (identação, espaçamento, etc).
  • ESLint, para a verificação de erros e padronização do código (nomenclatura de variáveis, etc).
  • Husky, para a execução automática do Prettier e ESLint antes de cada commit/push.
• Não deixe texto solto no código, utilize arquivos de tradução.
  • Utilize o arquivo src/locales/en.json para textos em inglês, e src/locales/pt_br.json para textos em português.
  • Utilize uma biblioteca de tradução, como react-i18next, para traduzir os textos, mesmo que o projeto não tenha suporte a múltiplos idiomas.
  • Isso permite que o projeto tenha suporte a múltiplos idiomas no futuro, sem que seja necessário alterar o código, além de facilitar a manutenção do código (por exemplo, para alterar um texto, basta alterar o arquivo de tradução, ao invés de alterar o código e procurar por todos os lugares onde o texto aparece).

Boas práticas de estilização

O mais importante é que o projeto tenha um estilo consistente e seja responsivo (isto é, funcione em diferentes tamanhos de tela). Isto porque, hoje em dia, os usuários acessam o projeto utilizando diferentes dispositivos, como computadores, tablets e celulares, e diferentes navegadores, como Chrome, Firefox, Safari, etc. Portanto, é importante que o projeto funcione em todos estes dispositivos e navegadores sem que seja necessário alterar o código para cada dispositivo e navegador individualmente.

• Aplique um estilo global utilizando o arquivo src/index.css.
  • Utilize o arquivo src/index.css para definir estilos globais, como fontes, cores, etc.
  • Utilize o arquivo src/index.css para importar fontes, imagens, etc.
  • Lembre-se que cada navegador possui um estilo padrão, portanto, é necessário resetar o estilo do navegador.
    • Utilize o arquivo src/index.css para resetar o estilo do navegador.
    • Algumas bibliotecas de componentes já resetam o estilo do navegador, portanto, verifique se a biblioteca de componentes utilizada já resetou o estilo do navegador.
    • Caso este não seja o caso, algumas propriedades comuns de serem alteradas são:
      • box-sizing: border-box;
      • margin: 0;
      • padding: 0;
      • img { display: block; max-width: 100%; }
      • a { text-decoration: none; }
      • button { border: none; }
      • button:focus { outline: none; }
      • ul { list-style: none; }
    • Estas são apenas algumas propriedades comuns de serem alteradas, portanto, verifique se o estilo do navegador foi resetado corretamente.
• Crie um arquivo para cada recurso, isto é, página ou componente.
• Cuide ao definir tamanho e posição dos elementos.
  • Quando utilizar px:
    • Utilize px para definir o tamanho de elementos que não devem ser redimensionados, como imagens, por exemplo.
    • Utilize para definir bordas, sombras, etc.
  • Quando utilizar rem:
    • Utilize rem para definir o tamanho de elementos que devem ser redimensionados, como padding, margin, etc.
    • Utilize rem para definir o tamanho de fontes, caso o tamanho da fonte deva ser redimensionado.
  • Quando utilizar %:
    • Utilize % para definir o tamanho de elementos que devem ser redimensionados, como width, height, etc.
• Funções úteis em CSS:
  • calc(): permite realizar operações matemáticas.
    • Exemplo: width: calc(100% - 20px);
    • Exemplo: width: calc(100% / 3);
    • Exemplo: width: calc(100% / 3 - 20px);
  • min(): retorna o menor valor.
    • Exemplo: width: min(100%, 300px);
      • Neste exemplo, o elemento terá no máximo 300px de largura.
    • Exemplo: width: min(100% / 3, 300px);
      • Neste exemplo, o elemento terá no máximo 300px de largura, ou 1/3 da largura da tela, o que for menor.
  • max(): retorna o maior valor.
    • Exemplo: width: max(100%, 8rem);
      • Neste exemplo, o elemento terá no mínimo 8rem de largura.
    • Exemplo: width: max(100% / 6, 8rem);
      • Neste exemplo, o elemento terá no mínimo 8rem de largura, ou 1/6 da largura da tela, o que for maior.
  • clamp(): retorna um valor entre um valor mínimo e um valor máximo.
    • Exemplo: width: clamp(8rem, 100% / 6, 20rem);
      • Neste exemplo, o elemento terá no mínimo 8rem de largura, ou 1/6 da largura da tela, ou no máximo 20rem de largura.
    • Exemplo: width: clamp(8rem, 100% / 6, 100%);
      • Neste exemplo, o elemento terá no mínimo 8rem de largura, ou 1/6 da largura da tela, ou no máximo 100% da largura da tela.
  • É possível misturar estas regras, por exemplo:
    • width: clamp(8rem, min(100% / 6, 20rem), 100%);
      • Neste exemplo, o elemento terá no mínimo 8rem de largura, ou 1/6 da largura da tela, ou no máximo 20rem de largura, ou no máximo 100% da largura da tela.