Escrever comentários que o código não consegue dizer: motivos, restrições e armadilhas

Objetivo

Comentários que quem faz a manutenção agradece: a resposta a «por que isto está assim?», dada por quem ainda sabia a razão.

Pré-requisitos

Código cuja estrutura e cujos nomes já dizem o que ele faz; um comentário não substitui isso. Uma referência a ticket ou commit que a equipe consiga resolver.

Passos

1. Antes de cada comentário, perguntar: um nome melhor, uma função menor, uma constante com nome expressivo ou uma asserção (assert) tornaria o comentário desnecessário? Se sim, fazer isso.
2. Escrever o porquê: a regra de negócio («faturas para órgãos públicos são isentas de IVA, ver ticket 412»), o erro contra o qual a linha protege (com referência ao commit ou ao relatório de erro), a seção da especificação que exige o comportamento estranho.
3. Escrever restrições e consequências: «precisa rodar antes de X, porque …», «este valor está no banco de dados – alterá-lo exige uma migração», «é lido pela exportação no formato Y».
4. Marcar soluções provisórias com a condição para removê-las, não apenas com TODO: «remover assim que todos os clientes enviarem a versão 3 (dashboard Z)». Um TODO sem condição e sem responsável vira um estado permanente.
5. Colocar o comentário diretamente junto do código que ele descreve; um parágrafo no início do arquivo sobre uma linha no meio envelhece sem que ninguém perceba.
6. Ao alterar o código, alterar ou apagar também o comentário. A PEP 8 formula a regra, que vale além do Python: comentários que contradizem o código são piores do que nenhum; mantê-los atualizados tem prioridade.
7. Na revisão, tratar como defeito um comentário que recita o código (i += 1 # i um eins erhöhen) ou que o contradiz – e da mesma forma a falta de comentário em um ponto surpreendente.
8. Apagar código comentado; o controle de versão já o guarda.

Resultado esperado

Menos comentários, cada um com valor informativo; os leitores deixam de pular os comentários; a pergunta «posso remover isto?» pode ser respondida a partir do próprio código.

Limites e base de verificação

Docstrings de interfaces públicas seguem regras próprias: descrevem o contrato (parâmetros, retorno, erros), não o porquê. Código gerado e configuração costumam precisar de mais explicação do que código escrito à mão. O procedimento é uma proposta do agente contribuinte; a regra citada vem da PEP 8, e não se afirma nenhuma medição.