Comentários e código

A parte básica todo mundo já sabe: não escreva comentários que explicam o que o código faz, porque o código já faz isso. Comentário desatualizado é pior do que nenhum comentário.

Mas tem um conjunto de alternativas que vão além do “usa nomes descritivos” — e que a maioria não considera.

Escreva a regra de negócio no código, não acima dele

Quando você sente a vontade de escrever um comentário explicando uma condição, considere se dá pra transformar essa condição em código legível.

// antes — o comentário carrega o contexto
// usuários do plano legado criados antes de 2022 não pagam taxa
if (user.plan === 'legacy' && user.createdAt < new Date('2022-02-01')) {
  return basePrice;
}

// depois — o código carrega o contexto
const LEGACY_PLAN_CUTOFF = new Date('2022-02-01');
const isExemptFromConversionFee =
  user.plan === 'legacy' && user.createdAt < LEGACY_PLAN_CUTOFF;

if (isExemptFromConversionFee) {
  return basePrice;
}

isExemptFromConversionFee diz exatamente o que está acontecendo. Se a regra mudar, o nome da variável vai parecer errado — o que é melhor do que um comentário silenciosamente desatualizado.

Testes são documentação com garantia

Um nome de teste bem escrito descreve comportamento melhor do que qualquer comentário — e tem uma vantagem que comentário não tem: ele quebra se o comportamento mudar.

it('não cobra taxa de conversão para usuários do plano legado criados antes de janeiro de 2022', () => {
  ...
});

Isso é documentação executável. Se alguém alterar a lógica de cobrança sem atualizar o teste, o CI avisa. Um comentário nunca avisa.

O “por que” vive no commit, não no código

Comentários que explicam decisões — “escolhemos X em vez de Y por causa de Z” — ficam desatualizados junto com o código. O lugar certo pra essa informação é a mensagem de commit.

fix: usa polling em vez de webhook no pagamento

O endpoint de webhook do provedor tem instabilidade em ambiente de staging.
Voltamos pro polling até o suporte confirmar que está resolvido.
Ref: #4521

git blame na linha te leva direto ao commit com o contexto completo. Comentário no código não tem essa rastreabilidade.

Comentário de região é sinal de função grande demais

function processPayment(order) {
  // ── validação ──────────────────
  ...

  // ── cálculo ────────────────────
  ...

  // ── persistência ───────────────
  ...
}

Se você está usando comentários pra dividir seções dentro de uma função, a função está grande demais. Cada seção provavelmente é uma função separada esperando pra existir. O comentário de região é o sintoma — a função grande é o problema.

Código comentado não é backup

// const result = oldCalculation(order);
const result = newCalculation(order);

Esse código não deveria existir em nenhuma branch. O histórico do git guarda a versão antiga. Código comentado acumula, ninguém sabe se pode apagar, e vira ruído permanente na base de código.

TODO é uma promessa que ninguém vai cumprir

// TODO: refatorar isso depois
// TODO: adicionar validação aqui
// TODO: entender por que esse número é 42

Se for importante, vira um ticket. Se não for importante o suficiente pra virar um ticket, provavelmente não vai ser feito. O TODO fica pra sempre, perde o contexto, e ninguém sabe se ainda é relevante.

Quando o comentário é necessário mesmo

Com tudo isso, há casos em que o comentário é a ferramenta certa — quando nenhuma das alternativas acima consegue carregar o contexto.

Workaround de bug externo:

// Contornando bug do react-pdf@3.1.2 que duplica headers em tabelas multi-página.
// https://github.com/diegomura/react-pdf/issues/1234
// Remover quando atualizar para 3.2.x
const headers = isFirstPage ? columns : [];

Regra de negócio com origem externa ao código — requisito legal, acordo contratual, limitação de sistema legado — onde não dá refatorar o contexto pra dentro do código.

Matemática não trivial com referência à fórmula ou fonte.

A diferença entre um comentário necessário e um comentário desnecessário é simples: o necessário explica algo que o código não consegue expressar por conta própria. O desnecessário explica o próprio código — e esse é o trabalho do código.