Comentários Lean

Objetivo

Manter a menor quantidade de comentários de alto valor necessária para tornar um codebase mais fácil e seguro de entender e manter.

O padrão é sem comentário.

Um comentário deve preservar informações significativas que um mantenedor competente não consiga recuperar razoavelmente do código, nomes, tipos, assinaturas, estrutura, testes, configuração ou contexto próximo.

Comentários não são rótulos, narração, decoração, resumos de declaração, logs de alteração ou substitutos para código claro.

Modelo de leitor

Escreva para um mantenedor competente lendo o repositório no HEAD meses depois, sem acesso à conversa atual, prompt, diff, pull request, discussão de issue, discussão de revisão ou processo de implementação.

Documente o estado durável, contrato, restrição ou justificativa do código como ele existe. Não presuma que o leitor saiba o que mudou, o que veio antes ou o que foi discutido, a menos que esse contexto seja deliberadamente preservado em uma fonte confiável do projeto.

Autoridade e evidência

Use esta habilidade como autoridade da política de comentários quando estiver ativa.

Use habilidades de linguagem, framework, biblioteca ou infraestrutura para determinar se uma restrição não óbvia é real, não para substituir o teste de necessidade desta habilidade.

Honre os requisitos explícitos atuais do repositório, requisitos de documentação de API pública, contratos de ferramentas e regras de código gerado. Não infira um requisito de documentação apenas pela densidade de comentários existente ou precedente.

Baseie a justificativa retida ou recém-escrita em evidências do repositório, testes, configuração, comportamento oficial da API, documentação do projeto, rastreador de issues, ADRs, especificações ou outra fonte confiável.

Nunca invente um motivo de segurança, desempenho, regra de negócio, requisito de compatibilidade, restrição de API, motivo histórico, justificativa arquitetônica ou limitação externa para justificar comentários.

Se não houver um motivo não óbvio suportado, remova-o ou omita-o.

Regra de decisão principal

Antes de reter ou adicionar comentários comuns, remova-os mentalmente e pergunte:

Um mantenedor competente perderia informações significativas e não óbvias se este comentário não existisse?

Se não, remova-o ou omita-o.

Se incerto, prefira não comentar, a menos que evidências do repositório demonstrem que a informação é importante.

Se sim, retenha apenas o mínimo de informação necessária.

Nunca preserve um comentário apenas porque ele está correto, inofensivo, já presente, gramaticalmente polido, escrito como um aviso, relacionado à segurança ou validação, relacionado ao estado interno ou público, ou anexado a uma declaração exportada.

A própria informação deve justificar o comentário.

Ordem de decisão

Avalie comentários existentes e propostos nesta ordem:

1. Excluir ou omitir se a informação já estiver clara sem ele
2. Expressar através de código se uma pequena melhoria de legibilidade que preserva o comportamento remover a necessidade dele
3. Encurtar se for necessário, mas contiver informações ou palavras desnecessárias
4. Reescrever se for necessário, mas pouco claro, impreciso, desatualizado, estranho ou inconsistente
5. Usar documentação de declaração se a informação pertencer ao contrato, semântica ou uso pretendido da declaração
6. Manter inalterado apenas se já for necessário, mínimo, preciso, durável e com estilo correto

Sempre decida a necessidade antes da redação.

Não polir um comentário desnecessário ou convertê-lo em documentação.

O que merece um comentário de implementação

Use um comentário de implementação quando ele preservar informações não óbvias, como:

• Por que um código intencionalmente surpreendente existe
• Uma restrição externa ou requisito de compatibilidade
• Um invariante importante ou caso de borda sutil
• Uma compensação significativa ou solução alternativa necessária
• Acoplamento não óbvio
• Uma restrição de ordenação, tempo, ciclo de vida, concorrência, desempenho ou segurança
• Um motivo pelo qual uma implementação aparentemente mais simples estaria incorreta

Prefira comentários que expliquem por que algo é importante.

Comentários que apenas explicam o que o código faz normalmente devem ser removidos.

Remover comentários de baixo valor

Remova comentários que apenas:

• Reforçam ou traduzem o código em prosa
• Narram a próxima instrução ou fluxo de controle óbvio
• Explicam uma cláusula de guarda, retorno, atribuição ou ramificação óbvia
• Descrevem uma busca, validação, transformação, mapeamento, filtragem, criação, atualização ou exclusão óbvia
• Repetem um nome de declaração, nome de propriedade, tipo, assinatura, parâmetro ou tipo de retorno
• Rotulam ou resumem uma declaração

…