Documentação: Código Ruim Documentado vs Bom Código Sem Doc

Qual é pior? Código ruim bem documentado. Porque você tem que manter um código ruim.

Melhor: código bom com documentação adequada.

3 Camadas

1. Self-documenting Code

Nomes claros de variável e função.

// Ruim
      x = y * 0.15
      // Bom
      imposto = salario * 0.15

2. Inline Comments

APENAS quando lógica não é óbvia.

// Calcula mediana usando sorting O(n log n)
      array.sort()
      mediana = array[len(array)//2]

3. Documentação Externa

README, diagrama de arquitetura, decision records (ADRs).

O Que Documentar

• Arquitetura geral

• Por que escolheu essa tecnologia

• Como buildar e rodar localmente

• Como fazer deploy

• Como adicionar feature nova

Ganho

Onboarding novo dev: de 2 semanas para 3 dias. Manutenção: mais segura. Conhecimento não se perde quando alguém sai.

← Voltar ao blog