- Por que não comentários de “por que não”? Não é por que "não há comentários"
- “Por que vocês não deixam comentários sobre ‘por que isso não deu certo’? Não estou perguntando por que vocês ‘não colocaram comentários’.”
Por que não comentários de “por que não”
- O código é escrito em uma linguagem de máquina estruturada, enquanto os comentários são escritos em uma linguagem humana rica em expressividade
- A ideia não é comentar o "o quê", mas incluir o máximo possível de informação nos identificadores
- Recentemente, também há quem defenda que o "por quê" não deve ficar nos comentários, mas sim em
LongFunctionNames ou nos nomes dos casos de teste
- Um codebase "autodocumentado" adiciona documentação por meio dos identificadores
Exemplo recente
- Exemplo vindo de
Logic for Programmers
- Surgiu um problema em que a build do epub não conseguia converter símbolos matemáticos (
\forall) no caractere correspondente (∀)
- Foi escrito um script para substituir manualmente os tokens das strings matemáticas por Unicode
- Ele foi implementado substituindo separadamente cada um dos 16 símbolos matemáticos, mas isso é ineficiente
- Isso foi resolvido com um comentário simples
- "Repete 16 vezes para cada string, mas o livro atualmente só tem 25 strings matemáticas e a maioria tem menos de 5 caracteres, então ainda é rápido o suficiente"
Por que comentar
- Motivos para comentar mesmo quando código lento não causa problemas
- No futuro, o código pode vir a se tornar um problema
- O comentário mostra que o trade-off foi reconhecido
- Ao revisitar o projeto depois, dá para entender por que o código lento foi escrito
Por que a autodocumentação é impossível
- Nomes longos de função como
RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs não explicam o trade-off
- Identificadores de funções e variáveis só conseguem conter um tipo de informação
- Também não é possível substituir comentários por testes
- A autodocumentação explica o que o código faz, mas a informação negativa explica o que o código não faz
Especulação no fim da newsletter
- Há a curiosidade sobre se comentários de "por que não" podem ser vistos como casos contrafactuais
- As abstrações da comunicação humana tornam a autodocumentação impossível?
- É possível autodocumentar metáforas, incerteza, argumentos éticos etc.?
Resumo do GN⁺
- Este texto trata da importância dos comentários de código e de seus limites
- Comentários deixam os trade-offs do código mais claros e facilitam a manutenção futura
- O texto enfatiza os limites da autodocumentação e a necessidade de comentários
1 comentários
Comentários do Hacker News
Ao comentar código, explico principalmente o "porquê" e "por que não funciona". Em código complexo, também é útil explicar brevemente o "o quê"
Engenheiros juniores escrevem comentários explicando o que o código faz, engenheiros de nível pleno explicam por que foi escrito dessa forma, e engenheiros seniores explicam por que não foi escrito de outro jeito
Uso um template de comentário para mantenedores
É importante comentar as partes surpreendentes do código
Reforça-se a importância dos comentários, especialmente quando você mesmo pode ter que manter seu código depois de 5, 10 ou 15 anos
É bom comentar o que "não é a solução ingênua"
É bom incluir comentários em nomes longos de funções ou de casos de teste
Também é útil adicionar avisos via debug logging quando a entrada fica maior do que as restrições originalmente previstas no design
Prefiro usar muitos comentários e comentários de documentação
Em code review, escrevo comentários como "A razão para não fazer X é Y" para evitar antecipadamente críticas esperadas