Com muita frequência, vejo código mal comentado. Aqui estão algumas diretrizes que tento seguir para comentários:
- Descreva apenas como quando complicado
- Sempre descreva o que
- Faça isso no nível de arquivo / módulo, classe e função / método
- Você pode evitar fazer isso para funções / métodos quando eles são muito curtos ou óbvios
- Descreva o porquê, se não for óbvio
- Que é na maioria das vezes
- Mais importante do que o quê e como, já que você pode eventualmente descobrir isso lendo o código
- Use um guia de estilo que cubra comentários e consulte-o com frequência
Eu adoraria ouvir sugestões para melhorar essas diretrizes!