Avez-vous commenter votre code?

Question

J'ai l'habitude de commentaire "fi" et d'écrire en "langage humain" de ce qu'il signifie, comme "vérifie si c'est A ou B".

Je trouve que c'est mieux pour les programmeurs juniors que de lire le code pour lire ce que cela signifie d'abord et ensuite analyser la déclaration (pour moi aussi quand je suis à la vérification de l'ancien code)

Que faites-vous? Quels sont les autres scénarios? Pros? Les inconvénients?

Answer 1

Les commentaires ne doivent pas être "comment" quelque chose est fait, mais plutôt "pourquoi" c'est fait (sauf dans le cas TRÈS rare où le comment n'est pas évident à partir de la lecture du code, et je veux dire que c'est SUPER RARE).

Answer 2

Jeff a un awesome post sur le sujet. Les liens dans le post et certains le blog, les réactions sont également la peine de lire.

Answer 3

Il y a une faille tragique avec "l'auto-documentation du code" de la théorie. Oui, la lecture du code vais vous dire exactement ce qu'il fait. Toutefois, le code est incapable de vous dire ce que c'est censé faire.

Je pense qu'il est sûr de dire que tous les bugs sont causés lorsque le code ne fait pas ce qu'il est censé faire :). Donc, si nous ajoutons quelques commentaires clés pour fournir des responsables ayant assez d'informations pour savoir ce qu'est un morceau de code est censé faire, alors nous leur avons donné la possibilité de résoudre tout un tas de bugs.

Cela nous laisse avec la question de savoir comment de nombreux commentaires. Si vous avez un trop grand nombre de commentaires, les choses deviennent fastidieux à entretenir et les commentaires vont inévitablement être à jour avec le code. Si vous mettez trop peu, alors qu'ils ne sont pas particulièrement utiles.

J'ai trouvé régulièrement des commentaires pour être le plus utile dans les endroits suivants:

1) Une brève description dans la partie supérieure d'un .h ou .fichier cpp pour une classe pour expliquer le but de la classe

2) Un bloc de commentaire avant la mise en œuvre d'un non-triviaux de la fonction d'expliquer le but et les détails de sa durée d'entrées, le potentiel de sorties, et de toutes les bizarreries de s'attendre lors de l'appel de la fonction.

Autre que cela, j'ai tendance à commenter tout ce qui peut paraître déroutant ou bizarre pour quelqu'un. Par exemple: "Ce tableau est basé sur 1 au lieu de 0 basée parce que de bla bla".

Answer 4

J'ai appris à la dure à code pour le plus petit dénominateur commun. Qui englobe beaucoup de comportements.

1. commentaire blocs de code, pas nécessairement chaque ligne. Expliquer pourquoi le bloc suivant (ou section) de code est écrit de la façon dont il est. Inclure une date et vos initiales dans le commentaire, de sorte que vous savez quand le commentaire a été mis en et qui a écrit le commentaire. Essayez d'éviter les commentaires comme "c'est stupide" ou "je suis tellement sacrément brillant" comme il n'a vraiment pas l'aider, et peut-être tort dans l'avenir. Si vous utilisez une fantaisie ou de faire quelque chose qui n'est pas évidente à partir d'un rapide coup d'œil, d'expliquer en quoi et pourquoi.

2. utilisation lisible par l'homme, les noms de variables. que les moyens d'éviter à une seule lettre, des variables comme la peste. il est beaucoup plus facile de deviner ce qu'une boucle ne si la variable d'index est appelé rowIndex que je. Presque tous les civilisés de la langue a un compilateur ou l'interpréteur sera frotter hors les noms de variables avant de mettre votre travail en code machine, afin de l'utiliser cryptique les noms de variable ne fait pas de faveurs.

3. rappelez-vous que les compilateurs sont intelligents. Très intelligent. Chaque compilateur sait comment optimiser les boucles et d'autres choses de base. L'écriture d'un complet tout en boucle sur une seule ligne peut regarder la fantaisie pour vous, mais il compile les mêmes, le voyage jusqu'à d'autres personnes à la recherche de votre code (et vous-même si vous revenez sur le code en quelques semaines). Éviter de fantaisie langue astuces si ils rendre le code moins lisible.

4. adopter un style et s'y tenir. Toujours faire fi, les boucles, etc dans le même format (et même indentation). Vous serez en mesure de repérer les différentes caractéristiques de votre code plus facilement parce que les mêmes fonctionnalités seront les mêmes. Si vous faites une erreur, il se démarquer un peu plus.

Faire ces choses rendent le code plus lisible pour tout le monde. Adopter de bonnes habitudes de codage réduit la dépendance sur les commentaires, trop, donc c'est un double-gagnant.

Answer 5

J'ai l'habitude de commentaire "fi" et d'écrire en "langage humain" de ce qu'il signifie, comme "vérifie si c'est A ou B".

Si vous vous retrouver à faire cela, il peut être préférable de refactoriser de sorte que le complexe de la logique booléenne est extrait à l'autre méthode, ou au moins d'introduire une variable avec un nom qui indique clairement que la logique des moyens.

Le problème avec les commentaires, c'est qu'ils (parfois) d'enfreindre la DRY (Don't Repeat Yourself) la directive. Lorsque vous dupliquez la logique en l'ajoutant à la documentation, même dans les commentaires du code, vous courez le risque d'avoir les choses tombent en dehors de la date. Bientôt, les commentaires devenues incomplètes ou inexactes.

Cela dit, je n'ai pas l'esprit en regardant les commentaires, même s'ils sont un peu hors de date. J'ai couru dans un code qui ressemble à ceci:

// collect data
Data data = collectData();
// analyze data
Report report = analyze(data);
// print report
report.print();

Ces types de commentaires sont absolument sans valeur pour tout le monde et en général, je vais les supprimer à vue.