|
|
|
# Melhores práticas de padrão de código
|
|
|
|
|
|
|
|
| [Home](home) | [AGES I](AGES_I) | [AGES II](AGES_II) | [AGES III](AGES_III) | [AGES IV](AGES_IV) | [**Padrão de Código**](padrao_de_codigo)
|
|
|
|
| :----------: | :-------------------------------: | :------------------: | :--------------: | :--------------------------: | :--------------------------: |
|
|
|
|
|
|
|
|
## Sumário
|
|
|
|
|
|
|
|
- [Introdução](#introdução)
|
|
|
|
- [Boas práticas gerais](#boas-práticas-gerais)
|
|
|
|
- [Boas práticas de git](#boas-práticas-de-git)
|
|
|
|
- [Boas práticas de banco de dados](#boas-práticas-de-banco-de-dados)
|
|
|
|
- [Boas práticas do back-end (Restful API)](#boas-práticas-do-back-end-restful-api)
|
|
|
|
- [Boas práticas do front-end](#boas-práticas-do-front-end)
|
|
|
|
- [Boas práticas de estilização](#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](https://material-ui.com/) 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](https://prettier.io/), para a estilização do código (identação, espaçamento, etc).
|
|
|
|
- [ESLint](https://eslint.org/), para a verificação de erros e padronização do código (nomenclatura de variáveis, etc).
|
|
|
|
- [Husky](https://typicode.github.io/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](https://react.i18next.com/), 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. |
