Comment gérer la tautologie dans les commentaires? [fermé]


54

Parfois, je me trouve dans des situations où la partie de code que j'écris est (ou semble être ) tellement évidente que son nom serait essentiellement répété sous forme de commentaire:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(Exemple en C #, mais merci de vous référer à la question comme étant indépendante de la langue).

Un commentaire comme celui-là est inutile. Qu'est-ce que je fais mal? Est-ce le choix du nom qui est faux? Comment pourrais-je commenter des parties comme celle-ci mieux? Devrais-je ignorer le commentaire pour des choses comme celle-ci?


8
Remarque: j'estime que "l'emplacement de la mise à jour" est très vague, à moins que la nature de "une mise à jour" ne soit parfaitement claire. Le système prend-il en charge d'autres types d'URI que les URL?

34
return result # returns result
Lukas Stejskal

27
La manière de traiter la tautologie dans les commentaires est la manière de traiter la tautologie dans les commentaires. (Ceci est un commentaire.)
Rex Kerr

29
Ce n'est pas vraiment un commentaire, il s'agit en réalité d'une documentation écrite sous la forme d'un commentaire. Différentes règles s'appliquent à la documentation de l'API par rapport aux commentaires de code intégrés.
Cody Gray

10
Ceci est simplement un exemple de mauvaise documentation API, pas de commentaires de code. Ma mise en forme XML C # pour une propriété comme celle-ci ressemblerait à quelque chose comme "Obtient ou définit un Uri pouvant être utilisé pour accéder au serveur de mise à jour de cet objet".
Kevin McCormick

Réponses:


13

Dans la plupart des projets sur lesquels je travaille, il n’ya pas beaucoup de temps pour écrire des commentaires détaillés sur chaque membre du groupe.

Cela ne signifie pas qu'il n'y a pas de temps pour les commentaires; au contraire, il reste suffisamment de temps pour les commentaires tautologiques qui renvoient une version reformulée de tout ce qui est commenté. Ils fonctionnent très bien comme point de départ .

Surtout compte tenu de l'utilisation par Visual Studio des commentaires accompagnant IntelliSense , il est judicieux de commencer par un bref aperçu du champ:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Et puis, au fur et à mesure que vous continuez à coder, lorsque vous ne vous rappelez plus s’il UpdateLocations’agissait de l’emplacement où la mise à jour a eu lieu ou de l’envoi de la mise à jour, vous devrez revisiter le code. C'est à ce stade que vous devriez ajouter ces informations supplémentaires:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Si jamais un autre programmeur vous demande des détails sur un champ, mettez à jour les commentaires avec ces informations:

Quel type de mise à jour doit Example.UpdateLocationêtre utilisé pour stocker?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Tout comme un programme contient des bogues, les bons commentaires ont des bogues qui doivent être résolus de manière itérative. Le but des commentaires est de vous aider à comprendre le code lorsque vous le revisitez six mois plus tard et que vous ne vous souvenez plus de rien du fonctionnement du programme.

Et tout comme la programmation, vos commentaires doivent commencer quelque part. Les commentaires tautologiques sont les Hello World!commentaires. Au fur et à mesure que vous vous entraînez à écrire et à mettre à jour une documentation, votre documentation de départ deviendra de plus en plus résistante.


+1 pour être le seul à donner un autre commentaire; plutôt que de simples réponses tautologiques.
Ian Boyd

C'est en fait la meilleure réponse à ce jour.
Roland Tepp

1
Dans mon projet actuel, j'ai été frappé plus que je ne pouvais compter par le manque de commentaires sur une base de code héritée importante. Quelque chose En tant qu'auteur, vous pensez que la méthode s'appelle de façon flagrante et que vous considérez une fonctionnalité plutôt évidente, elle risque de ne pas être aussi auto-documentée dans trois mois par un autre développeur. La documentation sur les méthodes, les propriétés et les champs doit essayer de replacer le contexte dans son ensemble et cette réponse explique le meilleur processus pour atteindre cet objectif, que j'ai déjà vu.
Roland Tepp

1
@RolandTepp, je comprends tout à fait d'où vous venez. Et je suis complètement d'accord. Selon moi, le problème est que beaucoup de programmeurs voient les commentaires et la documentation comme quelque chose qui se produit une fois que le code est terminé et prêt à être envoyé, plutôt que comme une chose qui se passe avec le code dans le processus de développement, nécessitant un suivi des bogues et des heures d'assistance. avec le reste du code.
zzzzBov

54

Les commentaires ne doivent jamais dupliquer votre code. Les commentaires ne doivent pas répondre à la question " comment? ", Mais seulement " pourquoi? " Et " quoi? ". Pourquoi un tel algorithme est choisi, quelles sont les hypothèses implicites ici (à moins que votre langage ne soit assez puissant pour l'exprimer avec un système de types, des contrats ou similaires), quelle est la raison de faire cela, etc.

Je vous recommande de jeter un coup d'œil à la pratique de la programmation alphabète pour vous inspirer.


+1 - c'est la réponse! Nous n'avons pas besoin de commentaires comme "Declare variables", "Increment counter" (dans une boucle), etc.
ozz

Ainsi, dans l'exemple du PO, quel serait un bon commentaire?
Départ

4
@stijn, je ne sais pas - il manque (évidemment) du code. Quelque chose que seul l'auteur du code connaît de son but et de ses limites.
SK-logic

Peut-être quelques commentaires comme // Mises à jour les raiseShielders selon le levelOfAttack (transmis sous forme d'URL)
woliveirajr

15
La question la plus importante à laquelle un commentaire devrait répondre est " WTF? "
naught101

53

Les commentaires doivent décrire le code, pas le dupliquer. Ce commentaire d'en-tête ne fait que dupliquer. Laisser de côté.


17
+1: Je pense comprendre ce que vous voulez dire, mais je ne suis pas d'accord avec ce que vous avez dit :-) Autant que possible, le code devrait décrire le code, alors que les commentaires devraient décrire votre raisonnement.
Kramii Rétablir Monica

3
@Kramii, malheureusement, le code est incapable de décrire le code, même si vous codez en Agda. Aucune langue n'est aussi puissante et expressive que la langue naturelle. Et souvent, vous aurez besoin de tracés, de graphiques, de tableaux, de formules complexes pour décrire le code - à peine possible sans une programmation alphabète appropriée.
SK-logic

6
@ SK-logic: je ne suis pas d'accord. Une méthode longue est moins auto-descriptive qu'une méthode courte qui appelle une série de sous-routines bien nommées.
Kramii Réintègre Monica

3
@ Kramii, désolé, je ne vois pas ce avec quoi vous êtes en désaccord et en quoi votre commentaire est lié à ce que j'ai dit. Mon point est que beaucoup de renseignements devraient être fournis avec votre code, ce qui est totalement absent du code lui-même. Toute l'histoire des décisions que vous avez prises, toutes les références pertinentes aux articles, etc. - il n'y a pas d'éléments linguistiques permettant d'exprimer de telles choses. Et les méthodes / fonctions / sous-routines / tout ce qui est long ou court n’est absolument pas pertinent ici.
SK-logic

2
@ SK-logic, ce que Kramii dit signifie: "Le code doit être facile à lire et à se comprendre" et tous les graphiques, etc. que vous mentionnez, entrent dans ce qu'il dit: "les commentaires doivent décrire votre raisonnement"
Shahbaz

36

Laissez les dehors!

Normalement, il est de bonne pratique de supprimer les commentaires lorsque les informations qu’ils contiennent sont déjà présentes ailleurs. Si vous pouvez exprimer clairement et sans ambiguïté le but d'une méthode en lui donnant un nom, il n'est pas nécessaire de faire de commentaire .

Mettez les dedans!

Votre exemple illustre deux exceptions à cette règle:

Tout d'abord, "UpdateLocation" peut (en fonction du contexte) être ambigu. Dans ce cas, vous devez soit lui donner un meilleur nom, soit un commentaire pour lever l’ambiguïté. Améliorer le nom est généralement la meilleure option, mais cela n’est pas toujours possible (lorsque vous implémentez une API publiée, par exemple).

Deuxièmement, le "///" dans C # indique un commentaire destiné à être utilisé pour générer automatiquement de la documentation. L'EDI utilise ces commentaires pour créer des info-bulles et il existe des outils (Sandcastle) pouvant générer des fichiers d'aide, etc. à partir de ces commentaires. En tant que tels, il existe des arguments pour insérer ces commentaires même si les méthodes qu’elles documentent portent déjà des noms descriptifs. Même dans ce cas, cependant, de nombreux développeurs expérimentés s'offusqueraient de la duplication d'informations. Le facteur décisif devrait être les besoins de ceux à qui la documentation est destinée.


C'est la meilleure réponse. Vous devriez pouvoir déterminer exactement à quoi servira la propriété lorsque vous consommerez la classe Example et survolerez la propriété.
Andy

Dans ces situations, je m'efforce (et échoue souvent) d'ajouter au moins l'un <remarks/>ou l' autre <see/>afin de fournir un contenu supplémentaire. Le <summary/>est toujours dupliqué, mais le commentaire dans son ensemble n'est pas complètement inutile.
earlNameless

20

Je suis fortement en désaccord avec les réponses "ne pas écrire de commentaires". Pourquoi? Permettez-moi de souligner en changeant un peu votre exemple.

public Uri UpdateLocation ();

Alors, que fait cette fonction:

  • Renvoie-t-il "l'emplacement de mise à jour"? ou
  • Est-ce qu'il "met à jour" l'emplacement et renvoie le nouvel emplacement?

Vous pouvez voir que sans commentaire, il y a ambiguïté. Un nouveau venu peut facilement faire l'erreur.

Dans votre exemple, comme il s'agit d'une propriété, les méthodes "get / set" révèlent que la deuxième option est incorrecte et signifie en effet "update location" et non "update the location". Mais il est beaucoup trop facile de faire cette erreur, surtout dans les cas de mots ambigus tels que "update". Jouer en toute sécurité. Ne confondez pas quelqu'un de nouveau avec ceci simplement pour avoir économisé quelques secondes de votre temps.


4
Je ne pense pas que quiconque préconise de ne pas écrire de commentaires du tout. La plupart / tous disent "écrivez les commentaires appropriés", ce à quoi l'exemple UpdateLocation pourrait être associé.
Ozz

16
Uri UpdateLocation()serait rejeté par la révision du code et modifié soit Uri GetUpdateLocation()ou void UpdateLocation().
avril

4
@avakar: d'accord avec le sentiment, mais comme il s'agit d'une propriété C # (les propriétés get et set sont automatiquement synthétisées et portent le même nom), le fait de renommer le GetUpdateLocationcode en GetUpdateLocation = somelocation. LocationOfUpdateserait un meilleur nom, ce qui supprime l'ambiguïté. Le problème fondamental est que l'OP utilisait un préfixe de verbe au lieu d'un nom. Les verbes en tête sont supposés indiquer l'action d'une méthode.
Ant

2
@DPD, "Combien de temps et d'efforts faut-il pour relier une ligne", combien d'efforts faut-il pour le maintenir? Combien de temps d'écran perd-il? Combien de temps cela perd-il quand il finit par être désynchronisé avec le code et à semer la confusion chez les développeurs?
Avakar

1
La méthode retourne une valeur et a un nom de phrase verbale. C'est le problème. Il devrait avoir un nom nominal. par exemple, 'Uri LocationOfUpdate ()'. Pas GetUpdateLocation, dites-vous “quelle est votre GetLocation?”?
ctrl-alt-delor

14

/// <summary>les blocs sont utilisés pour générer la documentation pour IntelliSense et la documentation API .

Ainsi, s'il s'agit d'une API destinée au public, vous devez toujours inclure au moins un <summary>commentaire, même si le but de la fonction doit être évident pour les lecteurs.

Cependant, c'est l'exception à la règle; en général, rappelez-vous simplement de sécher (ne vous répétez pas) .


5

Ne remplissez les commentaires de ce type que si vous savez comment tirer profit de telles choses; sinon il suffit de les essuyer.

Pour moi, l’ avantage évident est qu’il existait une vérification automatique des commentaires manquants et que je l’utilisais pour détecter le code dans lequel des informations importantes devaient être renseignées; pour cela, je remplissais bien certains espaces réservés - juste pour m'assurer que le rapport d'outil ne contenait pas de "fausses alarmes".

Je pense qu'il y a toujours un moyen d' éviter la duplication flagrante . Au fil des années, j’ai commencé à utiliser quelques "modèles de remplisseurs" pour des cas comme le vôtre - la plupart du temps comme un nom auto-descriptif et voir ci-dessus .

Pour cet exemple particulier, j'utiliserais quelque chose de "type auto-descriptif" (en supposant que ce ne soit pas le cas où l'effacement ferait le travail), comme ceci:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Par exemple, lorsque je pourrais utiliser voir ci-dessus, les remplisseurs gentils seraient les commentaires Javadoc qui nécessitent des champs dédiés pour la valeur de retour, les paramètres et les exceptions. Très souvent, j'estime qu'il est plus logique de décrire la plupart, voire toutes ces choses, en une phrase récapitulative unique, méthode qui retourne <décrire ce qui est renvoyé> pour les paramètres fournis <decrire les paramètres> . Dans de tels cas, je remplis formellement les champs obligatoires en clair, voir ci-dessus , en indiquant au lecteur la description sommaire.


3

Voici une question que j’aime poser lorsqu’on se demande s’il faut ajouter un commentaire dans une section de code: Que puis-je dire qui aiderait la personne suivante à mieux comprendre l’ intention générale du code, de manière à pouvoir mettre à jour, corriger ou l'étendre plus rapidement et de manière plus fiable?

Parfois, la bonne réponse à cette question est qu'il n'y a rien que vous puissiez ajouter à ce stade du code, car vous avez déjà sélectionné des noms et des conventions qui rendent l'intention aussi évidente que possible. Cela signifie que vous avez écrit du code solide auto-documenté, et que l'insertion d'un commentaire nuirait probablement à plus que cela ne serait utile. (Notez que les commentaires redondants peuvent effectivement nuire à la fiabilité du code au fil du temps en ralentissant le décalage avec le code réel et en rendant ainsi plus difficile le déchiffrement de l’intention réelle.

Cependant, dans presque tous les programmes et tous les langages de programmation, vous rencontrerez des points où certains concepts et décisions critiques pris par le programmeur original - par vous - ne seront plus évidents dans le code. C’est à peu près inévitable, car un bon programmeur programme toujours pour l’avenir - c’est-à-dire, pas seulement pour que le programme fonctionne une fois, mais pour que tous les nombreux correctifs, versions, extensions, modifications et ports à venir, et qui sait quoi faire. fonctionne également correctement. Ce dernier ensemble d’objectifs est beaucoup plus difficile et nécessite plus de réflexion pour réussir. Il est également très difficile d’exprimer correctement dans la plupart des langages informatiques, qui sont plus centrés sur la fonctionnalité - c’est-à-dire dire ce que cela fait. version du programme doit faire, maintenant, afin de le rendre satisfaisant.

Voici un exemple simple de ce que je veux dire. Dans la plupart des langues, une recherche rapide en ligne dans une petite structure de données sera suffisamment complexe pour que quelqu'un qui la consultera pour la première fois ne reconnaisse probablement pas immédiatement ce dont il s'agit. C'est une opportunité pour un bon commentaire, car vous pouvez ajouter quelque chose à propos de l' intention de votre code qu'un lecteur ultérieur appréciera probablement tout de suite comme utile pour déchiffrer les détails.

Inversement, dans des langages tels que le langage logique Prolog, l'expression de la recherche dans une petite liste peut être si incroyablement triviale et succincte que tout commentaire que vous pourriez ajouter ne serait que bruit. Un bon commentaire dépend donc nécessairement du contexte. Cela inclut des facteurs tels que les points forts de la langue que vous utilisez et le contexte général du programme.

L'essentiel est la suivante: Penser à l'avenir. Demandez-vous ce qui est important et évident pour vous sur la manière dont le programme devrait être compris et modifié à l'avenir. [1]

Pour les parties de votre code qui sont vraiment auto-documentées, les commentaires ne font qu'ajouter du bruit et aggraver le problème de cohérence des versions futures. Alors ne les ajoutez pas là.

Mais pour les parties de votre code pour lesquelles vous avez pris une décision critique parmi plusieurs options ou pour lesquelles le code lui-même est suffisamment complexe pour que son objectif soit obscur, ajoutez vos connaissances spéciales sous forme de commentaire. Un bon commentaire dans un tel cas est celui qui permet à un futur programmeur de savoir ce qui doit être conservé - c'est le concept d'une assertion invariante, accessoirement - et ce qui est OK pour changer.


[1] Cela va au-delà de la question des commentaires, mais cela vaut la peine d'être abordé: si vous avez une idée très précise de la façon dont votre code pourrait changer à l'avenir, vous devriez probablement aller au-delà du simple commentaire et intégrer ces paramètres. dans le code lui-même, car ce sera presque toujours un moyen plus fiable d'assurer la fiabilité des versions futures de votre code que d'essayer d'utiliser des commentaires pour guider une future personne inconnue dans la bonne direction. Dans le même temps, vous souhaitez également éviter une généralisation excessive, car les humains sont notoirement mal à même de prédire l'avenir, ce qui inclut l'avenir des modifications apportées au programme. Donc, essayez de définir et de capturer les dimensions raisonnables et éprouvées de l’avenir à tous les niveaux de la conception du programme.


3

Dans mon propre code, je laisserai souvent des tautologies de commentaires en place, y compris celles particulièrement flagrantes telles que:

<?php
// return the result
return $result;
?>

... ce qui contribue évidemment peu à rendre le code plus compréhensible d'un point de vue explicatif.

Dans mon esprit, cependant, ces commentaires ont toujours une valeur s'ils aident à maintenir la cohérence visuelle des motifs de couleur dans votre surligneur de syntaxe .

Je pense que le code a une structure très similaire à la langue anglaise, en ce sens qu’il existe des "phrases" et des "paragraphes" (même si un "paragraphe" peut être entièrement constitué d’une "phrase" unique). J'inclus habituellement un saut de ligne et un résumé d'une ligne au-dessus de chaque "paragraphe". Par exemple:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ignorez le code incomplet, les injections SQL, etc. Vous avez l'idée.)

Pour moi, le commentaire final ajoute véritablement de la valeur au code, simplement parce qu'il aide à délimiter visuellement un "paragraphe" d'un autre en maintenant un schéma de coloration cohérent.


J'ai du mal à faire mettre la coloration syntaxique en surbrillance dans ma réponse. Si un éditeur peut arriver derrière moi et le faire fonctionner, je l’apprécierais vraiment, étant donné que les couleurs sont importantes pour mon argumentation.
Chris Allen Lane


2

Les commentaires doivent être utilisés pour l'une des actions suivantes.

  1. Informations à saisir pour les générateurs de documents. Cela ne peut pas être sous-estimé, c'est extrêmement important.
  2. Avertissements indiquant pourquoi un élément de code est ce qu'il est, et quelles autres considérations. J'ai traité du code écrit dans 2 langages de programmation. Un élément clé de cette stratégie consistait à établir une structure commune entre les deux langues. Un commentaire sur les deux sites informant l'utilisateur que s'il change ce numéro, il doit aussi en changer un autre est extrêmement utile.
  3. Rédigez des notes pour expliquer pourquoi un code particulièrement étrange est ce qu'il est. Si vous deviez réfléchir à la manière de faire fonctionner un morceau de code d'une manière particulière, et que la solution ne soit pas évidente dès le début, il vaudrait probablement la peine d'expliquer ce que vous tentiez de faire.
  4. Étiquetage des entrées / sorties, si elles ne sont pas claires. Il est toujours bon de savoir quelles sont vos entrées et leur format.

Les commentaires ne doivent pas être utilisés pour:

  1. Expliquez les choses qui sont extrêmement évidentes. Une fois , je code hérité de scie comme ceci: page=0; // Sets the page to 0. Je pense que toute personne compétente pourrait comprendre cela.

2

Je voudrais supprimer la tautologie mais garder le commentaire, je commenterais les propriétés et les noms de variables en donnant une valeur d'échantillon, afin que l'utilisation soit bien comprise:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Maintenant, je sais exactement ce qui se passe là-dedans et, à partir du commentaire, j'ai une idée claire de la façon de l'utiliser.


0

Je dirais que cela dépend du but des commentaires.

S'ils doivent être utilisés pour générer de la documentation à l'intention de l'équipe qui la construit (ou si ce ne sont que des commentaires en ligne pour expliquer des choses), alors je pense qu'il est acceptable de laisser cela de côté. On peut supposer sans risque que cela va de soi. et quand ce n'est pas le cas, d'autres membres de l'équipe à proximité peuvent l'expliquer. Bien sûr, s'il s'avère que cela ne va pas de soi pour beaucoup de gens, vous devriez l'ajouter.

Si les commentaires génèrent de la documentation pour une équipe éloignée géographiquement, je mettrais toute la documentation à l'intérieur.


0

Je pense que ce sujet a été discuté assez longuement sous des noms tels que "comments: anti-patterns", ou "les commentaires sont-ils une odeur de code?" ( un exemple ).

J'ai tendance à être d'accord avec l'idée générale selon laquelle les commentaires devraient ajouter de nouvelles informations, pas des doublons. En ajoutant de tels commentaires triviaux, vous violez DRY et réduisez le rapport signal sur bruit du code. J'ai tendance à trouver les commentaires de haut niveau expliquant les responsabilités, la raison d'être et les exemples d'utilisation de la classe beaucoup plus utiles que les commentaires par propriété (surtout ceux qui sont superflus).

Personnellement, dans votre exemple, je laisserais de côté les commentaires (s’il n’ya rien d’utile à ajouter au sujet de la propriété).


0

Si vous pouvez écrire du code ne nécessitant pas de commentaire, vous avez programmé nirvana !.

Moins votre code nécessite de commentaires, meilleur sera le code!


3
Ce n'est pas possible (et ne le sera jamais). Il y a toujours beaucoup d'éléments cachés derrière le code - hypothèses implicites, décisions architecturales, longues chaînes de transformations mathématiques aboutissant à un algorithme spécifique, etc.
SK-logic

1
Peut-être "Hello World!" est programmeur nirvana alors ...
naught101

: -} - C'est quelque chose qui est très rarement atteint - le problème est que si vous avez du mal à trouver un commentaire qui donne un sens, soyez simplement satisfait de vous-même, cela signifie que votre code est juste!
James Anderson

0

Un commentaire comme celui-là est inutile. Qu'est-ce que je fais mal?

Cela ne semble inutile que si vous savez déjà ce qui se UpdateLocationpasse. Est-ce que "update" est ici un verbe ou un nom adjoint? Autrement dit, est-ce quelque chose qui met à jour l'emplacement ou est-ce l'emplacement de la mise à jour? On pourrait déduire de cette dernière du fait qu’il UpdateLocations’agit apparemment d’une propriété, mais le point le plus important est qu’il n’est parfois pas gênant d’énoncer explicitement quelque chose qui semble évident.


0

En dehors de la documentation automatiquement compilée, le code devrait se documenter lui-même, de sorte que les commentaires ne doivent documenter que le code ne suffit pas à se documenter.


-1

"Emplacement" est assez évident, mais "Mise à jour" pourrait être un peu vague. Si vous ne pouvez pas écrire un meilleur nom, pouvez-vous donner plus de détails dans le commentaire? Mise à jour de quoi? Pourquoi avons nous besoin de ça? Quelles sont certaines hypothèses (est null admissible)?

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.