Comentar hoje em dia é mais fácil do que nunca. Em Java, existem algumas boas técnicas para vincular comentários a classes, e os Java IDEs são bons em criar shells para você. Idiomas como Clojure até permitem adicionar uma descrição de uma função no próprio código de função como argumento.
No entanto, ainda vivemos em uma época em que frequentemente existem comentários obsoletos ou ruins escritos por bons desenvolvedores - estou interessado em melhorar a robustez e a utilidade dos meus comentários.
Em particular, estou interessado em Java / Clojure / Python aqui, mas as respostas não precisam ser específicas da linguagem.
Existem técnicas emergentes que validam comentários e detectam automaticamente comentários "frágeis" (por exemplo, comentários com números mágicos, frases incompletas etc.) ou comentários incorretos (por exemplo, detecção de variáveis com erros ortográficos ou similares).
E mais importante: existem "políticas de comentários" ou estratégias aceitas por aí? Existem muitos conselhos sobre como codificar - mas e quanto a "como comentar?"
Isso pode ser controverso, mas meu conselho seria escrever o menor número possível de comentários. Use nomes de classe claros e agradáveis, nomes de variáveis e nomes de métodos. Escreva seu código da maneira mais clara possível; e considere que esse é o atributo mais importante do seu código (exceto que ele atende aos requisitos). Escreva um comentário apenas se você tiver deixado o método o mais claro possível e ainda achar que ele exige mais explicações.
E tenha uma prática organizacional, que sempre que alguém mudar de classe de alguma forma, precisará garantir que os comentários ainda estejam corretos.
fonte
if (a == b) then c();faz, mas se eu não sei por que ele faz - é quando um comentário deve ser usado :) #Não tenho certeza de outras linguagens, mas o python permite que você escreva doctests, que são uma forma de comentários com validação automática. Obviamente, eles não devem ser usados no lugar de testes de unidade reais, mas são um método rápido e fácil de documentar funções específicas que podem não ser tão óbvias quanto deveriam. Eles vêm com o benefício adicional de poder executar os testes de comentários para verificar se os comentários ainda estão corretos (pelo menos a parte deles que contém testes).
fonte
Um dos locais mais autorizados para descobrir como usar o comentário de código para gerar documentação automaticamente é certamente doxygen . Embora pudesse me dar mais dessas ferramentas.
Isso define o padrão de redação de comentários que deve ser seguido para gerar automaticamente a documentação. No entanto, isso fornece mais estrutura, mas não é validado semanticamente; por exemplo, não é possível verificar se você usou inglês enganoso para descrever o objetivo de uma função!
Embora essa seja a melhor coisa que faz comentários estruturados, pessoalmente sinto que há mais documentação necessária para tornar o código mais sustentável. Algum tempo atrás, havia uma pergunta no P.SE O código pode ser a documentação nas ferramentas de desenvolvedor de código aberto? Com que frequência é? Obviamente, isso também se aplica a projetos não de código aberto.
Para tornar o código mais sustentável - é praticamente mais importante que exista uma documentação externa que ajude a criar uma estrutura de como tratar o código e, em seguida, os comentários dentro do código devem ser restritos para ver
Penso que, se você deseja definir as políticas para escrever comentários, deve incluir como uma abordagem holística incluída no padrão de codificação. Veja o seguinte: Quais podem ser algumas armadilhas na introdução de um guia de estilo e documentação para gerar software em uma equipe de desenvolvimento?
Normalmente, um comentário constitui menos de 5% do código. E, na prática, embora as próprias revisões de código atraiam muito menos atenção (sobre outros aspectos do desenvolvimento), é praticamente difícil que os comentários também sejam revisados.
fonte
Existe uma técnica bem conhecida - é chamada de "revisão de código" e tem uma irmã chamada "programação de pares". Não espere nada "automagicamente" aqui.
"Código completo" contém não apenas tudo sobre como codificar, mas também capítulos sobre "como comentar", especialmente sobre como escrever código de auto-documentação.
fonte
Específico para Java, uma fonte que eu gostei é o Oracle How to Write Doc Comments para a Javadoc Tool :
E Item 44: Escreva comentários de documentos para todos os elementos expostos da API :
do Effective Java 2nd Edition .
fonte