Melhores Práticas

melhores-praticas.md

Melhores Práticas

1. Documentação Adequada

Manter uma documentação adequada é fundamental para facilitar a manutenção do código da equipe como um todo. Isso inclui:

• Documentação de código com comentários significativos: Comentários no código devem ser informativos e explicar o que o código faz, a lógica por trás dele e quaisquer considerações especiais. Seguindo o padrão de idioma do código: língua inglesa.

  Dica: use o ChatGPT para gerar Docstrings

• Guias de instalação e uso: Forneça instruções claras sobre como configurar o ambiente de desenvolvimento, instalar dependências e executar o software. Isso ajuda novos membros da equipe a se integrarem mais rapidamente.

Referência: Criando Comentários no Python da Forma Correta

2. Padrões de Codificação do Projeto

Manter padrões de codificação consistentes é importante para garantir a legibilidade e a manutenibilidade do código. Alguns padrões incluem:

• Código em inglês: Usar o inglês como idioma padrão para nomes de variáveis, funções e comentários, já que não se sabe quem terá acesso ao código.

• Django app com letra minúscula: Seguir a convenção de nomear os aplicativos Django com letras minúsculas.

• Nunca commitar migrações do Django: Evitar adicionar arquivos de migrações gerados pelo Django ao repositório de código. Atualmente incluído como regra no .gitignore.

• Commits devem possuir poucas mudanças: Ou seja: commite constantamente.

  • Também é preferível que suas mensagens de commit estejam em inglês.

• Padrões de string: Manter padrões consistentes para representação de strings, seja com aspas duplas ou simples. Ex.:

  • String com aspas duplas :"string"
  • Caracteres com aspas simples: 'c'

• Guia de estilo de código Python: seguir o PEP8

  • Referência: https://peps.python.org/pep-0008/

• Sempre rodar o "Linter" antes de abrir PR: Linters ajudam a garantir que seu código seja de alta qualidade, aderindo às melhores práticas da comunidade Python.

  • Referência: Python3 Linter: O Guia Definitivo para Melhorar a Qualidade do seu Código

3. Commits Semânticos

O uso de mensagens de commit descritivas e semânticas é crucial para facilitar o entendimento das alterações no código-fonte por todos os membros da equipe. Isso ajuda na rastreabilidade das mudanças e na compreensão das motivações por trás delas.

Referência: Padrões de commits semânticos

4. Controle de Versão

O projeto utiliza o sistema de controle de versão Git, seguindo políticas claras de branch e merge, incluindo o padrão Git Flow e commits semânticos. O padrão de nomenclatura para branch e commit é:

• Branch: git checkout -b "feat/function-name" (macro)
• Commit: git commit -m "chore:commit-message" (micro)

Referência: Boas práticas para escrita das mensagens de commits

Exemplo de Git Flow

Fluxo de trabalho com versionamento:

 1. Crie um novo branch no seu repositório local.
 2. Implemente suas mudanças
 3. Documente seu código para facilitar manutenção em equipe
 4. Faça o commit de suas mudanças seguindo o padrão de Commits Semânticos 
 5. Faça um pré-commit (vide README.md) para garantir a qualidade do código e do projeto
 6. Faça um push do seu branch para o repositório remoto
 7. Submeta um Pull Request seguindo o template de melhores práticas
 8. Aguarde a revisão do mesmo por outros desenvolvedores da sua equipe
 9. Caso alguma mudança seja solicitada, critique e implemente-a caso seja pertinente.
 10. Seus colegas de equipe integrarão seu código quando ele estiver ok.

Referência: Melhores práticas com o git

5. Pull Requests e Revisões de Código

O uso de pull requests (PRs) para incorporar código novo ou modificado, juntamente com revisões de código por pares, é prática comum para garantir a qualidade do código e promover a colaboração.

Referência: Boas práticas de revisão de código

6. Automatização de Testes

Para garantir a qualidade do código e a estabilidade das funcionalidades, é crucial implementar uma estratégia de teste abrangente que aborde diferentes aspectos.

• Testes dentro do Django Admin para garantir que as mudanças aos models foram implementadas e as operações administrativas estejam funcionando corretamente.

Isso também inclui o uso do framework de teste Pytest para a criação de testes:

• Testes unitários que verificam a corretude das unidades individuais de código
• Testes funcionais que avaliam o comportamento de componentes ou funcionalidades completas
• Testes de integração que verificam como agrupamentos de componentes funcionam quando utilizados juntos

Integrar esses testes ao processo de integração contínua (CI) proporciona uma abordagem proativa para identificar problemas de código, melhorando a confiabilidade e a manutenção do projeto.

Referencia: Diferença entre fases de teste, tipos de teste e formas de execução

7. Colaboração

O projeto utiliza ferramentas de colaboração, como sistemas de rastreamento de problemas (como a página de issues do GitHub), ferramentas de chat (como WhatsApp e Discord) e sistemas de gerenciamento de projetos (como o Trello) para facilitar a comunicação e a colaboração entre os membros da equipe.

Caso dois estejam colegas atuando em tasks diferentes para uma mesma FEATURE/STORIE/SCRUM, mergear as duas branchs e testar juntos o fluxo

8. Pair Programming

A prática de pair programming é muito importante para lidar com problemas complexos e integrar novos membros da equipe. Isso envolve dois desenvolvedores trabalhando juntos no código, onde um engenheiro atua como motorista, enquanto o segundo atua como navegador ou observador, fornecendo revisões em tempo real do código e alternando seus papéis conforme necessário. Além disso, mesclam suas branchs para testar o fluxo de trabalho. Embora a programação em par aumente as horas de trabalho necessárias para entregar o software, ela tem mostrado efeitos positivos nas taxas de defeitos no software. Sempre que puder, utilize o canal de pair-programming do Discord.

Referência: Pair Programming: Best Practices and Tools

9. Mentoria e Treinamento

Como todos sabem, este é um projeto para preparar profissionais juniors com demandas e escala projetos e procedimentos do mundo real. É importante mantermos um ambiente de aprendizado onde os membros experientes compartilhem conhecimento e que os membros menos experientes se sintam seguros em colaborar e perguntar.

10. Filosofias de Projeto Django

O projeto se orienta pelas filosofias de design do Django ao criar aplicativos Python web robustos e elegantes. Isso inclui seguir os princípios de "explicit is better than implicit" e "don't repeat yourself" para escrever código de alta qualidade.

Referência: Filosofias de design do Django