Skip to content

Documentação e Boas Práticas no Código

Importância da Documentação

Uma arquitetura bem planejada pode ser completamente comprometida por uma implementação desleixada. A documentação não é um extra, é o que transforma código em um sistema compreensível e sustentável a longo prazo, funcionando como uma bússola para desenvolvedores atuais e futuros.

A documentação eficaz vai muito além de comentários óbvios. Ela oferece benefícios tangíveis:

  • Reduz o tempo de onboarding de novos desenvolvedores em até 50% (Swimm, 2023)
  • Facilita a manutenção e evolução do sistema
  • Preserva o conhecimento do domínio e decisões arquiteturais
  • Permite que times trabalhem de forma independente e coordenada

Em resumo, a documentação e as boas práticas de código têm ligação com a arquitetura de software, pois ambos atentam a ter um projeto bem estruturado, organizado e fácil de ser compreendido por outros devs. O código tem que se autoexplicar para você.

1. Auto-Documentação através de Código Limpo

A melhor documentação é o próprio código. Priorize escrever código que seja fácil de ler e entender.

Princípios Práticos com Exemplos Reais

Nomenclatura Significativa - Use nomes que revelem intenção:

// Ruim - O que é 'd'? O que 'f' faz?
const d = 5;
function f(x) { return x * 2; }

// Bom - Auto-explicativo
const daysSinceAccountCreation = 5;
function calculateMonthlyRevenue(grossRevenue) { 
  return grossRevenue * 2; 
}

Funções com Propósito Único - Princípio da Responsabilidade Única:

// Uma função fazendo tudo - Frágil e difícil de testar
function processUserOrder(userData, paymentInfo, shippingDetails) {
  // 50 linhas fazendo validação, processamento, email, logging...
}

// Funções especializadas - Fáceis de testar e manter
function validateOrderData(order) { /* ... */ }
function processPayment(paymentInfo) { /* ... */ }
function sendOrderConfirmationEmail(userEmail, orderDetails) { /* ... */ }

Comentários que Explicam o "Porquê":

// Redundante - O código já é óbvio
// increment counter
counter++;

// Explica o contexto não óbvio
// Usar 5 como padrão devido à limitação da API legada (v2.1)
// Ticket: PROJ-123, Data: 2023-10-15
const DEFAULT_PAGE_SIZE = 5;

2. Documentação Técnica Estratégica

Nem tudo pode ser expresso apenas com código. Documente os aspectos arquiteturais e de decisão.

Estrutura de Documentação Recomendada

project-root/
├── docs/
│   ├── architecture/           # Decisões de arquitetura
│   │   ├── adrs/              # Architectural Decision Records
│   │   └── diagrams/          # Diagramas de fluxo e estrutura
│   ├── api/                   # Documentação de API
│   ├── components/            # Documentação de componentes
│   └── workflows/             # Fluxos de desenvolvimento
├── src/
└── README.md                  # Porta de entrada principal

Elementos Essenciais

README.md Principal - A porta de entrada do projeto:

# Nome do Projeto

Breve descrição do que faz e para quem.

## Começando Rápido
### Pré-requisitos
- Node.js 
- npm ou yarn

### Instalação
```bash
git clone [url-do-repositorio]
cd nome-do-projeto
npm install


**Executando o Projeto**

```bash
npm run dev

Estrutura do Projeto

src/
├── features/    # Funcionalidades organizadas por domínio de negócio
├── shared/      # Código compartilhado entre features
└── app/         # Configuração do framework (Next.js)

Testes

# Testes unitários
npm test

# Testes end-to-end
npm run test:e2e

# Coverage report
npm run test:coverage

Scripts Disponíveis

Script Descrição
dev Inicia servidor de desenvolvimento
build Gera build de produção
test Executa testes unitários
lint Executa análise estática do código

Troubleshooting

Erro de build no Windows

# Executar como administrador
npm install --no-optional

ADRs (Architectural Decision Records) - Documentando decisões importantes:

# ADR 001: Escolha do Gerenciador de Estado

## Status
Aceito - 2023-10-20

## Contexto
Necessidade de escolher uma solução para gerenciamento de estado global entre:
- Redux Toolkit
- Zustand
- Context API

O projeto possui 15+ componentes que compartilham estado complexo e requerem:
- Performance em atualizações frequentes
- DevTools para debugging
- Baixo boilerplate

## Decisão
Escolhemos **Zustand** pelos seguintes motivos:

### Vantagens
- Curva de aprendizado suave para a equipe
- Menos boilerplate comparado ao Redux Toolkit
- Performance comprovada em projetos similares
- Integração simplificada com React Query
- Bundle size reduzido (~2kB)

### Trade-offs
- Menos ferramentas de devtools que Redux
- Comunidade menor que Redux

## Consequências
### Positivas
- Desenvolvimento mais rápido
- Código mais limpo e maintainable
- Facilidade de testing

### Negativas
- Necessidade de customizar soluções para algumas funcionalidades
- Menos recursos de debugging out-of-the-box

## Alternativas Consideradas
### Redux Toolkit
- Ecossistema maduro
- Excelentes devtools
- Boilerplate significativo
- Curva de aprendizado mais íngreme

### Context API
- Built-in do React
- Zero dependencies
- Performance issues em atualizações frequentes
- Não é designed para estado global complexo

3.Práticas de Commit e Versionamento

A história do código é uma forma de documentação temporal que registra a evolução do seu projeto.

Commits Semânticos

Commits semânticos seguem uma estrutura padronizada que torna o histórico mais legível e útil:

tipo(escopo): mensagem concisa

[corpo detalhado opcional]

[rodapé opcional com referências]

Tipos de commit mais comuns:

Tipo Descrição Exemplo
feat Nova funcionalidade feat(auth): implementar login com Google
fix Correção de bug fix(checkout): corrigir cálculo de frete
docs Documentação docs: atualizar README com instruções de instalação
style Formatação de código style: padronizar indentação em componentes
refactor Refatoração sem mudança funcional refactor(api): simplificar lógica de busca
test Adição/modificação de testes test(user): adicionar testes para validação
chore Tarefas de manutenção chore: atualizar dependências

Boas Práticas para Commits

  1. Commits atômicos: cada commit deve representar uma única mudança lógica
  2. Mensagens claras: explique o quê e por quê, não o como
  3. Primeira linha: máximo 50 caracteres, sem ponto final
  4. Corpo do commit: quando necessário, use para explicar contexto e motivação
  5. Use o imperativo: "adicionar feature" em vez de "adicionada feature"

Exemplo de Fluxo de Trabalho com Git

# Antes de começar a trabalhar
git pull origin main

# Crie uma branch para sua tarefa
git checkout -b feature/login-social

# Faça suas alterações e commits atômicos
git add src/components/Login.js
git commit -m "feat(auth): adicionar botão de login com Google"

# Mais alterações
git add src/services/googleAuth.js
git commit -m "feat(auth): implementar serviço de autenticação Google"

# Envie para revisão
git push origin feature/login-social

Ferramentas Úteis

  • Commitizen: assistente para criar commits padronizados
  • Commitlint: verifica se commits seguem a convenção
  • Husky: permite configurar git hooks para validar commits
  • Standard Version: gera changelogs e versões automaticamente

Versionamento Semântico

Use o padrão SemVer (X.Y.Z) para versionar seu software:

  • X (Major): mudanças incompatíveis com versões anteriores
  • Y (Minor): novas funcionalidades compatíveis
  • Z (Patch): correções de bugs compatíveis

Exemplo: ao lançar uma versão 2.4.1:

  • 2 indica a segunda versão major
  • 4 indica a quarta atualização com novas funcionalidades
  • 1 indica a primeira correção de bug nesta minor

Tags Git para Versões

# Criar tag anotada
git tag -a v1.2.0 -m "Release v1.2.0: implementação do carrinho"

# Enviar tags para o repositório
git push origin --tags

Template para Pull Requests:

## Descrição das Mudanças
[Descreva o que foi alterado e por quê]

## Tipo de Mudança
- [ ] Nova funcionalidade
- [ ] Correção de bug
- [ ] Refatoração
- [ ] Documentação
- [ ] Performance
- [ ] Testes

## Checklist
- [ ] Testes adicionados/atualizados
- [ ] Documentação atualizada
- [ ] Build passando localmente
- [ ] Revisão de código solicitada

## Screenshots (se aplicável)
[Adicione screenshots para mudanças de UI]

4. Ferramentas que Apoiam a Documentação

Ferramenta Para que Serve Benefício Principal
TypeScript Tipagem estática Documentação em tempo de compilação
Storybook Documentação de UI Catálogo visual de componentes
JSDoc/TSDoc Documentação de funções Geração automática de docs
Husky Git hooks Verificação automática de qualidade
Swimm Docs sincronizadas Documentação sempre atualizada

5. Checklist de Documentação por Camada

Camada de Projeto

  • README.md com guia de início rápido
  • ADRs para decisões arquiteturais
  • Diagramas de arquitetura atualizados
  • Guia de contribuição claro

Camada de Componentes

  • Storybook com casos de uso
  • Props documentadas com TypeScript/TSDoc
  • Exemplos de uso para cada componente
  • Guidelines de quando usar cada componente

Camada de API

  • Swagger/OpenAPI para endpoints
  • Exemplos de request/response
  • Documentação de erros e status codes
  • Guia de autenticação e autorização

Camada de Testes

  • Estratégia de testes documentada
  • Coverage requirements claros
  • Guia para escrever bons testes
  • Exemplos de testes para patterns comuns

Conclusão

Vou concluir com essa citação "código bem documentado é como um mapa bem desenhado - ele não impede que você se perca, mas torna muito mais fácil encontrar o caminho de volta" (MadCap Software, 2023).

Próximos Passos Recomendados:

  1. Comece com um README.md claro
  2. Adicione TypeScript para documentação automática
  3. Implemente commits semânticos
  4. Escolha uma ferramenta de documentação (Storybook/Swimm)
  5. Documente decisões importantes com ADRs

Lembre-se: a melhor documentação é aquela que permanece atualizada porque é útil para quem a escreve.

Referências

  • Codacy (2023). Code Documentation: Best Practices and Tips. Disponível em: https://blog.codacy.com/code-documentation/
  • Swimm (2023). Code Documentation: Benefits, Challenges and Tips for Success. Disponível em: https://swimm.io/learn/code-documentation/
  • MadCap Software (2023). How to Write Code Documentation: Best Practices. Disponível em: https://www.madcapsoftware.com/blog/
  • Fireship (2021). Documentation that Doesn't Suck. YouTube. Disponível em: https://www.youtube.com/watch?v=ewBUaTcfTVk
  • Martin, R. C. (2017). Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall.
  • Fowler, M. (2002). Patterns of Enterprise Application Architecture. Addison-Wesley.