Tout d'abord, dans cette question, je voudrais rester à l'écart de la polémique sur la question de savoir si les commentaires sur le code source sont bons ou mauvais. J'essaie simplement de comprendre plus clairement ce que les gens veulent dire quand ils parlent de commentaires qui vous disent POURQUOI, QUOI ou COMMENT.
Nous voyons souvent des directives telles que "Les commentaires devraient vous dire POURQUOI; le code lui-même devrait vous dire COMMENT". Il est facile d’accepter l’affirmation à un niveau abstrait. Cependant, les gens laissent généralement tomber cela comme un dogme et quittent la pièce sans autre explication. J'ai vu cela utilisé dans tellement d'endroits et de contextes différents, qu'il semble que les gens puissent s'entendre sur le slogan, mais ils semblent parler de choses complètement différentes.
Revenons donc à la question: si les commentaires vous disent POURQUOI, de quoi s'agit-il, POURQUOI? Est-ce la raison pour laquelle ce morceau de code existe en premier lieu? Est-ce ce que ce code pièce devrait faire? J'apprécierais vraiment si quelqu'un pouvait donner une explication claire, puis ajouter quelques bons exemples (les mauvais exemples ne sont pas vraiment nécessaires, mais je ne peux pas les ajouter pour contraster).
Il y a beaucoup de questions sur le fait de savoir si les commentaires sont bons ou mauvais, mais personne ne répond à la question spécifique de savoir quels sont les bons exemples de commentaires qui vous disent POURQUOI.
la source
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY.
Si tout le monde fournit un exemple valable, alors toutes les réponses sont correctes. Le format de ce site Web est destiné à faciliter un processus de questions-réponses où toutes les réponses ne sont pas créées égales.Réponses:
L'exemple le plus courant et le plus distinctif concerne les commentaires sur diverses solutions de contournement. Par exemple celui-ci:
Vous trouverez sûrement plus d'exemples dans les sources Git et Linux; les deux projets essaient de suivre cette règle.
Je recommande également de suivre cette règle encore plus strictement avec les logs de commit . Pour les commentaires de code, il peut arriver que vous corrigiez le code, mais oubliez de mettre à jour le commentaire. Avec la quantité de code dans le projet habituel, il est garanti que cela arrivera tôt ou tard. D'autre part, le journal de validation est lié au changement particulier et peut être rappelé à l'aide de la fonctionnalité "annoter" / "accuser" du système de contrôle de version. Encore une fois, Git et Linux ont de bons exemples.
Regardez par exemple ce commit . (ne pas copier ici, c'est trop long). Il comporte quatre paragraphes qui prennent une page presque entière (et un peu trop d’écran) décrivant ce qui était faux exactement et pourquoi c’était faux, puis continue et modifie toutes les SIX lignes. Ils utilisent des commentaires comme celui-ci à deux fins:
(note: il m'a fallu au plus 10 minutes de navigation aléatoire dans le dépôt git pour arriver à ces deux exemples, il serait donc facile d'en trouver plus ici)
la source
Un commentaire qui explique pourquoi explique le raisonnement derrière le code - par exemple:
Un commentaire qui vous explique comment explique ce que fait le code.
La différence est qu'un responsable peut regarder le premier et dire: "Oh, alors c'est peut-être obsolète!" Dans le second cas, ledit responsable a un commentaire qui ne dit rien du code lui-même ne révèle pas (en supposant que les noms de variables sont corrects).
Voici un exemple concret de pourquoi, à partir d'un code iOS sur lequel j'ai travaillé pour obtenir une adresse de passerelle (ou une estimation raisonnable pour celle-ci). J'aurais pu laisser les commentaires qui disaient des choses comme "Initialiser la prise de réception", mais cela ne ferait que dire à un responsable (ou à moi futur) ce qui se passait, pas à la raison pour laquelle je devais faire cet étrange kludge pour obtenir l'adresse de la passerelle dans le répertoire. première place.
la source
Je voudrais commencer ma réponse par une citation de Jeff Atwood dans son article de blog Code vous dit comment, des commentaires vous expliquent pourquoi :
Il déclare également que:
Je suis tout à fait d’accord et à ce stade, je dois ajouter qu’avant de pouvoir commencer à rendre le code aussi simple que possible, je le fais fonctionner puis je commence à le refactoriser. Ainsi, lors de la première exécution avant la refactorisation, il est très utile d’ ajouter pourquoi les commentaires .
Par exemple, si vous utilisez 3 boucles imbriquées avec des tables de hachage bidimensionnelles pour remplir un tableau des jours de la semaine tout en analysant les données, il est très facile de perdre le fil de ce qui a été fait par quelqu'un ou même par vous-même si vous ne le regardez pas pendant quelques semaines et que vous le refactuez subitement.
La partie supérieure est un exemple de la façon dont 3 boucles imbriquées fonctionneraient avant la refactorisation.
Expliquer également certaines conditions de branche peut aider à comprendre le code beaucoup mieux avec ce que l’on pensait au cours du processus:
Même un code simple et évident fonctionne bien avec des commentaires. Juste pour rendre les choses un peu plus évidentes, plus claires ou plus faciles à comprendre pour vos collègues et même pour vous-même lors de la maintenance de logiciels.
Certes, xp dit que le code s’explique de lui-même, mais un commentaire d’une ligne fait-il mal?
Je trouve également les règles suivantes de ce blog très utiles:
Quiconque doit réintégrer son propre code ou quelqu'un d'autre ou même du code hérité sait que cela peut être un casse-tête. Donc, au lieu d’être paresseux ou d’essayer d’être un super codeur en ne commentant rien du tout ou très peu, pourquoi ne pas créer votre propre ou celui d’un pauvre pauvre, qui doit maintenir votre code, la vie future beaucoup plus facilement en suivant les règles citées.
De nombreuses décisions de programmation sont douteuses lors des révisions et la raison pour laquelle certaines parties ont été écrites n'est pas toujours claire, même si certaines sections de code sont vitales pour qu'un programme fonctionne, en raison d'un bogue majeur détecté car le code a été utilisé pendant des années. . Donc, pour ne pas vous ennuyer complètement avec un tl; dr avec une dernière citation d’ acmqueue :
la source
int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
est en erreur. Certainement devrait être... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
. Bonnes idées de commentaires - Mauvais code.J'ai tendance à réduire les commentaires à des références où une certaine fonctionnalité / code est expliquée plus en détail ou à expliquer pourquoi un certain mode de programmation est choisi.
Etant donné que d’autres programmeurs ayant des compétences similaires utilisent ou lisent votre code, il est important de faire un commentaire si vous utilisez une méthode différente de celle attendue. Vous pouvez donc expliquer dans un commentaire pourquoi vous avez choisi cette méthode.
Par exemple, si vous pouvez utiliser deux capteurs différents sur un appareil Android et que l’un ne correspond pas à vos besoins, vous pouvez expliquer dans le commentaire pourquoi vous avez choisi l’autre.
Le «pourquoi» devrait donc justifier vos choix.
la source
Les commentaires devraient vous dire ce que le code ne dit pas, pas nécessairement délimité par WHY , HOW ou WHAT . Si vous avez de bons noms et des fonctions bien délimitées, il est fort possible que le code puisse vous dire exactement ce qui se passe. Par exemple:
Ce code n'a vraiment pas besoin de commentaires. Les noms de fonction et de type facilitent la compréhension.
Parfois, cependant, il peut être difficile voire impossible de créer un code fluide comme ci-dessus. Par exemple, l'extrait de code suivant sert à trouver un point statistique sur une sphère. Les maths sont assez opaques, donc un commentaire avec un lien vers l'explication est utile pour aider à dire COMMENT ça marche. Cela peut être encapsulé dans une fonction pour dire CE qu’il fait sans avoir besoin de commentaire si besoin plus d’une fois, sinon le titre du lien est également utile dans ce département.
Un autre exemple de commentaire dans lequel les commentaires vous disent ce que le code ne permet pas est d’expliquer une décision. Dans l'exemple suivant, le code ne verrouille pas une variable non locale à un thread à l'intérieur d'un morceau de code threadé. Il y a une raison à cela et le commentaire explique POURQUOI . Sans le commentaire, cela pourrait être considéré comme un bug, ou simplement ne pas être remarqué.
Peut-être pourrait-on améliorer la raison pour laquelle l'objet aléatoire n'est pas créé à l'intérieur de la boucle parallèle en premier lieu. S'il n'y a pas de raison, cela pourrait aussi amener quelqu'un à venir et à se rendre compte que l'idée est stupide et constitue un bon endroit pour refactoriser.
la source
WriteText
de//
?Il peut être utile de reconnaître différents types de "pourquoi", notamment:
Les raisons pour lesquelles un code qui semble trop complexe ne fonctionneraient pas si elles étaient simplifiées (par exemple, une conversion de type apparemment superflue peut être nécessaire pour garantir que le code fonctionne dans certains cas critiques).
Les raisons pour lesquelles une opération simple et apparemment dangereuse est réellement sûre (par exemple, "notre routine d'extraction de données rapportera un élément factice passé comme dernier élément, comme étant inférieur à tout le reste, et l'élément suivant comme étant supérieur; tout élément devant être trié avant un autre, dans une séquence constante ascendante ou descendante, sera suivi par au moins un élément supplémentaire (éventuellement factice) ").
Dans de nombreux cas, un commentaire du second type dans une partie du code peut "correspondre" à un commentaire du premier type dans une autre (par exemple, "Bien qu'il semble que cette séquence d'opérations puisse être simplifiée, la routine Fitz repose sur le Wongle n’est pas Woozled tant que le Bandersnatch n’a pas été blanchi. ")
la source
N'oubliez pas que si vous écrivez un programme, vous ne faites pas que taper des choses au hasard, vous le faites parce que vous avez un modèle de ce que vous voulez , que ce soit dans un document officiel ou dans votre tête. Les choses dans votre tête sont aussi réelles que les logiciels / données d'un ordinateur (et tout aussi susceptibles de contenir des bugs).
Quelqu'un lisant votre code peut ne pas avoir ce modèle en tête, aussi les commentaires peuvent-ils servir à leur dire quel était le modèle et comment le code s'y rapporte. Je pense que c'est ce que l'on entend par "pourquoi". Certes, il est bon de rendre le code lui-même aussi explicite que possible, mais cela ne suffit pas toujours. Exemple:
En plus de cela, le modèle change avec le temps et ces modifications doivent être transférées dans le code. Les commentaires doivent donc non seulement indiquer «pourquoi», mais aussi comment le modifier en fonction des modifications prévues du modèle. Exemple:
Je pense que le but des commentaires est parfois négligé.
la source
Tous mes commentaires ne sont pas du type "pourquoi", mais beaucoup le sont.
Voici des exemples tirés d’un fichier source (Delphi):
Notez que (mon) pourquoi les commentaires précèdent généralement le code qui va le faire (donc se terminent par deux points).
Certains ont des commentaires expliquant uniquement ce qui se passe, par exemple, lorsqu'un processus comporte de nombreuses étapes comportant un regroupement logique (et que le code n'est pas remodelé pour le montrer automatiquement), je commenterai comme ceci:
la source
Je comprends que le POURQUOI est la raison pour laquelle vous faites quelque chose d'une manière peut-être étrange ou peut-être illogique, en raison des circonstances données qui l'exigent. Le HOW peut être vu dans le code lui-même, aussi étrange soit-il, même si le code n'a pas de "sens". La CE QUI est probablement mieux dit au début de la documentation classe / fonction. Cela vous laisse donc ajouter le POURQUOI , où vous expliquez tout ce qui ne figure pas dans les COMMENT et QUOI, et les manières particulières que vous devez suivre pour des raisons indépendantes de votre volonté.
Bien sûr, ce n'est pas toujours le cas, en dehors du pays des licornes et des arcs-en-ciel ...
COMMENT:
QUOI:
POURQUOI:
la source
critters.dance()
, alors le commentaire ne fait que répéter l'évident, et "nous ne pouvions pas le faire fonctionner avec une autre méthode que nous avons essayée" est totalement inutile. De plus, dire "nous appellerons la méthode pour chaque objet" revient à répéter ce que le code dit très clairement.J'ai appris à TOUJOURS écrire des commentaires dans les fichiers d'en-tête C ++ (car ce n'est pas toujours clair CE QUE fait une fonction, même si le nom lui donne un bon indice), surtout si vous transmettez une API à d'autres développeurs ou utilisez un outil d'autodoc tel que doxygen.
Donc, pour moi, un commentaire typique ressemble à quelque chose comme:
La seule fois où j'ai utilisé les commentaires WHY, c’est quelque chose de difficile à saisir et parfois même au programmeur, comme "NE PAS TOUCHER CETTE!! Parce que ..." ou "LE PROGRAMME CASSERA SI LA LIGNE EST SUPPRIMÉE ..."
Les solutions de contournement, les piratages et les comportements étranges sont éligibles aux critères POURQUOI à mes yeux ...
Un exemple très bon et même hilarant est cette "solution de contournement" pour du code gâché écrit par une personne nommée Richard, quelqu'un d'autre l'a emballé et a expliqué pourquoi dans les commentaires ... https://stackoverflow.com/a/184673/979785
Malheureusement, il y a plusieurs fois où vous êtes obligé d'envelopper bull **** parce que vous ne pouvez pas toucher à l'original, soit parce que "ça a toujours été comme ça" ou que vous n'avez pas accès ou ... eh bien, vous ne pas avoir le temps de réparer l'original pour le but n'est pas vraiment admissible pour les frais généraux.
la source
documentation
tag est regrettable mais ne s'applique toujours pas à la question).Le code est censé spécifier un plan d'exécution. De cette façon, le suiveur de programme (ou le compilateur) peut déterminer ce qu'il faut faire et comment le faire. Ce qui est divisé en étapes que le suiveur de programme peut suivre. Les étapes primitives sont le comment.
L'intention du codeur est une autre affaire. Dans un code simple, clair et simple, l'intention est évidente. Tout lecteur humain raisonnablement compétent arrivera à l'intention d'un bloc de code, simplement en lisant le code. La plupart du code devrait se lire comme ceci.
Parfois, la relation entre l'intention et le plan est obscure. Le code révèle le quoi et le comment, mais pas le pourquoi. C'est alors que les commentaires révélant l'intention en valent la peine. L'intention du programmeur est le pourquoi.
la source
Si ce problème se pose actuellement, nous allons parcourir des procédures stockées et des vues à l'aide d'un modèle de données complexe et quelque peu compliqué.
Nous avons (nombreux) des sélections composées comme "Cas où x.account n'est pas nul et x.address dans (sélectionnez l'adresse de fedex) puis x.account sinon y.account end" et une productivité attendue bien qu'il n'y ait pas de temps à perdre. tout pour lire tout le code source. Et cet exemple a en quelque sorte un sens, mais il reste impénétrable.
Les commentaires expliquant pourquoi dans fedex, alors x et sinon, y - fait la lumière sur l’ensemble du système et, lorsque nous en lisons suffisamment, nous commençons à l’obtenir. Et ceci est simplifié et il y a des centaines ou des milliers de déclarations similaires. Mon cœur brille chaleureusement à qui que ce soit le gentil développeur de 2007 qui a mis ces raisons.
Alors, oui, modèles de données complexes et complexes, procédures de sauvegarde et procédures stockées avec plusieurs chemins d'accès valablement nommés, veuillez nous dire pourquoi, s'il vous plaît, l'amour de D.ieu.
la source
Je viens d'écrire ce commentaire; c'est un exemple concret d'expliquer pourquoi une ligne de code est ce qu'elle est, et en particulier pourquoi je l'ai modifiée.
La méthode examine les données stockées et évalue si elles sont complètes à la date d'aujourd'hui et à la date de début à l'autre.
Comme vous pouvez probablement le deviner, l'opérateur supérieur à était un opérateur supérieur ou égal. Le commentaire explique pourquoi l'ancienne valeur a un sens et pourquoi la nouvelle valeur est meilleure. Si quelqu'un regarde cela à l'avenir, il verra que l'utilisation de ">" n'est pas un oubli, mais une optimisation. Ils peuvent ensuite le modifier ou le quitter, en fonction des besoins de l’époque.
la source