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

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?

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.

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.

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

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.

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.

/// <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) .

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.}

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.

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.

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.

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.

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.

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é).

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!

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.

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.

"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)?