Existe-t-il un guide définitif pour écrire des commentaires de code, destiné aux développeurs en herbe?
Idéalement, il couvrirait quand les commentaires devraient (et ne devraient pas) être utilisés, et quels commentaires devraient contenir.
Ne commentez pas CE QUE vous faites, mais POURQUOI vous le faites.
Le WHAT est pris en charge par un code propre, lisible et simple avec un choix approprié de noms de variables pour le prendre en charge. Les commentaires montrent une structure de niveau supérieur au code qui ne peut pas (ou est difficile à) montrer par le code lui-même.
se rapproche, mais c'est un peu concis pour les programmeurs inexpérimentés (une expansion à ce sujet avec plusieurs exemples et cas d'angle serait excellente, je pense).
Mise à jour : En plus des réponses ici, je pense que cette réponse à une autre question est très pertinente.