Guide du débutant pour rédiger des commentaires?

27

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.

Cette réponse :

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.

language-agnostic comments Cameron
la source
Je pense que nous nous dirigeons rapidement vers un monde où les gens ne font plus de commentaires. Pour le meilleur de (plus probable) pour le pire. Agile.
MK01
1
@MK: Si c'est le cas (j'ai tendance à être plus d'accord avec cette réponse ), alors un guide expliquant comment ne pas écrire de commentaires, et pourquoi ils devraient être évités, serait tout aussi utile. En fait, plus il y a de points de vue différents, mieux c'est.
Cameron
Je pense que les petits commentaires pour améliorer la vitesse de lecture du code sont très utiles et le seront toujours. Je n'achète pas entièrement le raisonnement du «commentaire périmé», même s'il est périmé, il aurait une valeur historique. J'avais l'habitude de travailler sur une base de code qui avait parfois des commentaires détaillés ici et là et je n'ai jamais été vraiment mordu par le fait que le commentaire était obsolète.
MK01
voir aussi: "Les commentaires sont une odeur de code"
gnat

Réponses:

38

Vous devez être conscient de la plus grande faiblesse des commentaires: ils deviennent périmés. Autrement dit, à mesure que le code change, les développeurs mettent rarement à jour les commentaires pour rester synchronisés avec le code. Cela signifie que vous ne pouvez jamais leur faire confiance et finir par lire le code. Pour cette raison même, votre code devrait être auto-documenté. Vous devriez choisir vos noms de fonction et de variable de telle manière que le code se lise comme de la prose.

Donc, ne documentez pas ce que fait le code. Le code d'auto-documentation devrait s'en occuper. Documentez POURQUOI vous le faites. Les POURQUOI sont généralement liés aux règles métier ou à l'architecture et ne changeront pas souvent et ne seront pas périmés aussi rapidement aux WHAT. Porte-documents. Documenter les exceptions. Documenter les décisions de conception. Et surtout, documentez les décisions de conception que vous aviez envisagées, mais avez décidé de ne pas mettre en œuvre (et documentez POURQUOI vous avez décidé de ne pas les utiliser).


la source
2
Le dernier est très important. Parfois, il y a un bug / effet secondaire avec l'implémentation de la solution évidente. La documentation des raisons pour lesquelles vous avez choisi d'utiliser une autre solution empêche le prochain développeur de réintroduire le bogue lorsqu'il "corrige" votre solution apparemment médiocre.
CaffGeek
2
Autre point, mon premier travail considérait les commentaires aussi importants que le code. Essayez de prendre l'habitude de lire les commentaires ainsi que le code lorsque vous passez en revue les pairs, et essayez d'insister pour que les commentaires soient à jour autant que possible. Cela permet d'éviter que les commentaires deviennent obsolètes et conserve les règles métier, etc. documentées dans votre code à jour.
Eric Hydrick
10

Vous devriez lire le livre Clean Code de Robert C. Martin . Cela explique bien que si vous avez besoin de commentaires, il est fort probable que vous ne codiez pas correctement. Idéalement, votre code devrait être «auto-commenté». Le livre Clean Coder explique comment procéder, afin que les commentaires ne soient pas nécessaires, et il décrivait bien comment faire des commentaires dans les situations où cela était nécessaire. (Comme expliquer une formule mathématique complexe)

Bob
la source
Bien que je ne voudrais pas tant une formule mathématique complexe expliqué que je voudrais qu'il écrit sur la notation mathématique appropriée (éventuellement TeX), avec une explication de son importance et de la source. Si vous ne comprenez pas la formule, vous ne devriez pas jouer avec le code qui l'utilise pour calculer une valeur, car vous êtes exceptionnellement susceptible de bousiller et d'introduire des bogues (subtils ou non).
un CVn
Le code peut seulement dire comment , pas pourquoi ou pourquoi pas . Vous avez besoin de commentaires pour cela.
7

Comme indiqué, Code Complete contient diverses directives sur la rédaction de commentaires. En bref, c'est PDL et peut se résumer comme suit:

  1. Décrivez votre intention, pas ce que fait le code. Évitez de décrire les détails de l'implémentation, sauf si vous utilisez une astuce ou si vous utilisez des implémentations personnalisées. Par exemple, utiliser des bits de décalage pour diviser, utiliser l'arithmétique du pointeur pour accéder aux membres de la classe ou utiliser un allocateur de mémoire personnalisé pour certains objets regroupés.

  2. Écrivez d'abord le pseudo-code (c'est-à-dire les commentaires), puis écrivez-le en vrai code une fois que vous avez fini de décrire votre routine / méthode / fonction. La langue utilisée est de haut niveau mais spécifique, elle peut donc être assez verbeuse

  3. Avoir une idée de ce que fait votre code avant même d'écrire le code

  4. Avoir des commentaires aussi proches que le code réel

Le but est d'éviter les commentaires non liés de longue haleine qui peuvent être obsolètes, mais d'avoir des commentaires reflétant l'intention et le but du code. L'utilisation d'un pseudo-code de haut niveau permet également de clarifier votre réflexion avant d'écrire l'implémentation.

Il y a un lien sur GameDev.net [qui explique PDL] [1], au cas où vous ne voudriez pas retrouver le livre.

Extrakun
la source
5
Écrivez d'abord le pseudo-code (c'est-à-dire les commentaires) . Je ne pouvais pas être plus en désaccord. Il n'y a pas de meilleur moyen de s'assurer que les commentaires ne correspondent pas au code. Les nouveaux codeurs (et le demandeur a spécifiquement demandé un guide pour les débutants) pirateront et refactoriseront les fonctions cent fois avant d'en être satisfaits, le code sera déplacé rapidement, réécrit, réutilisé et à la fin, ils peuvent ont une solution de travail élégante, mais elle ne ressemblera en rien à leur pseudo-code initial. Les commentaires seront-ils déplacés et mis à jour lorsqu'ils feront fonctionner le code? Vous pouvez parier que votre douce bippy ne le fera pas. Mes deux centimes.
Binary Worrier
1
De plus, les commentaires de pseudo-code vous diront ce que le code est censé faire. Le code devrait vous le dire. Le pseudo-code ne vous dira pas pourquoi le code le fait. -1 mec, désolé, mais je ne suis pas d'accord avec le deuxième point, les temps ont changé.
Binary Worrier
1
Pas pour discuter, mais plus d'explications - le pseudo-code est d'expliquer l'intention du code que vous avez écrit. Cela signifie que le commentaire ne concerne pas les détails d'implémentation (tels que "Ajouter x en haut de la pile") mais plutôt ce que le code est censé faire (comme "Faire apparaître la fenêtre devant tout le reste"). Comme vous l'avez souligné à juste titre, vous devez déplacer les commentaires avec le code. Je suis en désaccord avec le code peut vous dire ce que le code fait - tout le temps. Même si, un commentaire utile / précis (si je réussis à bien l'écrire!) Va très loin. En fin de compte, toujours à mon humble avis.
Extrakun
3
Une méthode ou une fonction appelée showWindowOnTop(window)sera toujours meilleure qu'un commentaire de même nature, tout cela est obsolète et mauvais conseil en 2012. 1) Les noms de fonction / méthode décrivent l'intention, 2) le pseudo-code est un exercice creux avec des chaînes d'outils modernes 3) Les tests vous indiquent ce que le code est censé faire avant de l'écrire, 4) un code bien nommé est meilleur que les commentaires qui ne correspondent pas à un code mal nommé
1

Ma suggestion serait d'écrire du code sans aucun commentaire, puis de m'en éloigner. Revenez-y dans un an et lisez-le. La partie que vous ne comprenez pas facilement est la partie que vous auriez dû commenter.

Kevin
la source
1
Hah, oui ;-) Ce n'est cependant pas un conseil particulièrement utile - cela aurait peut-être dû être un commentaire?
Cameron
la partie que vous ne comprenez pas que vous auriez dû écrire dans des parties plus petites et mieux nommées. La principale raison pour laquelle les commentaires sont insérés dans le code est que les fonctions / méthodes sont trop longues et devraient être de nombreuses petites pièces auto-documentées.
0

J'aime vraiment comment Evan Todd résume son point de vue sur les seules catégories de commentaires utiles ( citant son blog ):

  • Commentaires expliquant pourquoi, plutôt que quoi. Ce sont les plus utiles.
  • Commentaires avec quelques mots expliquant ce que fait le morceau de code géant suivant. Ils sont utiles pour la navigation et la lecture.
  • Commentaires dans la déclaration d'une structure de données, expliquant ce que signifie chaque champ. Celles-ci sont souvent inutiles, mais il n'est parfois pas possible de mapper intuitivement un concept à la mémoire, et des commentaires sont nécessaires pour décrire le mappage.
Cameron
la source