Comment traiter de la tautologie dans les commentaires?
Parfois, je me trouve dans des situations lorsque la partie du code que j'écris est (ou semble être) si évidente que son nom serait essentiellement répété comme un commentaire:
class Example
{
/// <summary>
/// The location of the update.
/// </summary>
public Uri UpdateLocation { get; set; };
}
(Exemple C #, mais veuillez vous reporter à la question comme langue-agnostique).
Un commentaire comme ça est inutile; Qu'est-ce que je fais mal? Est-ce le choix du nom qui ne va pas? Comment pourrais-je commenter des parties comme ça mieux? Devrais-je juste ignorer le commentaire pour des choses comme ça?
Dans la plupart des projets, je travaille sur, il n'y a pas de temps significatif pour écrire des commentaires détaillés sur chaque membre de la classe.
Cela ne signifie pas qu'il n'y a pas de temps pour des commentaires; Au contraire, il y a beaucoup de temps pour les commentaires tautologiques qui corrigent une version reformulée de tout ce qui est commenté. Ils fonctionnent bien comme un point de départ .
Surtout compte tenu de l'utilisation des commentaires de Visual Studio d'accompagnement IntelliSense , c'est une bonne idée de commencer avec un peu d'informations sur le terrain:
class Example
{
/// <summary>
/// The location of the update.
/// </summary>
public Uri UpdateLocation { get; set; };
}
Et ensuite, comme vous continuez à coder, quand Vous ne pouvez pas vous rappeler si UpdateLocation était l'emplacement que la mise à jour a eu lieu, ou l'emplacement que la mise à jour est envoyée à, vous " ll devra 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 pose des détails sur un champ, mettez à jour les commentaires avec ces informations:
Quel type de mise à jour devrait
Example.UpdateLocationêtre utilisé pour stocker?
class Example
{
/// <summary>
/// The Uri location where the Foo update took place.
/// </summary>
public Uri UpdateLocation { get; set; };
}
Comme un programme a des bugs, de bons commentaires ont des bugs qui doivent être élaborés itérativement. Le but des commentaires est d'aider à comprendre le code lorsque vous le revisitez six mois plus tard et que vous ne vous souvenez plus sur la manière dont le programme fonctionne.
Et comme la programmation, vos commentaires doivent commencer quelque part. Les commentaires tautologiques sont les Hello World! des commentaires, lorsque vous pratiquez l'écriture et la mise à jour de la documentation, votre documentation de départ deviendra de plus en plus résiliente.
Les commentaires doivent jamais Dupliquer votre code. Les commentaires ne doivent pas répondre au "Comment?" Question, mais seulement "pourquoi?" et "quoi?". Pourquoi un tel algorithme est choisi, quelles sont les hypothèses implicites ici (à moins que votre langue ne soit suffisamment puissante pour l'exprimer avec le système de type, les contrats et la même manière), quelle est la raison de faire cette chose du tout, etc.
Je recommanderais de jeter un coup d'œil à la pratique de programmation alphabète pour une inspiration.
Les commentaires doivent décrivez le code, pas le dupliquer. Ce commentaire de cet en-tête est juste des doublons. Laisser de côté.
Laissez-les sortir!
Normalement, il est une bonne pratique de supprimer les commentaires où les informations exprimées sont déjà présentes ailleurs. Si vous pouvez exprimer le but d'une méthode clairement et sans ambiguïté en donnant un bon nom, alors il n'y a pas besoin de commentaire .
Mettez-les!
Votre exemple illustre deux exceptions à cette règle:
Premièrement, "la mise à jour" peut (selon le contexte) être ambiguës. Dans ce cas, vous devez soit lui donner un meilleur nom, soit donner un commentaire pour supprimer l'ambiguïté. L'amélioration du nom est généralement la meilleure option, mais cela n'est pas toujours possible (lorsque vous mettez en œuvre une API publiée, par exemple).
Deuxièmement, le "///" en C # indique un commentaire destiné à être utilisé pour générer automatiquement une documentation. The IDE utilise ces commentaires sur Tool-Tips, et il existe des outils (Sandcastle) pouvant générer des fichiers d'aide, etc. Par conséquent, il y a des arguments d'insertion de ces commentaires même si Les méthodes qu'ils documentent ont déjà des noms descriptifs. Même lors, cependant, de nombreux développeurs expérimentés se traduiraient par la duplication des informations. Le facteur décisif devrait être les besoins de ceux pour lesquels la documentation est destinée.
Je suis fortement en désaccord avec les réponses "Ne pas écrire des commentaires". Pourquoi? Permettez-moi de signaler en changeant un peu votre exemple.
public Uri UpdateLocation ();
Alors, que fait cette fonction:
- Retourne-t-il "la mise à jour"? ou
- Est-ce qu'il "met à jour" l'emplacement et renvoie-t-il le nouvel emplacement?
Vous pouvez voir que sans commentaire, il y a une ambiguïté. Un nouveau compromis peut facilement faire l'erreur.
Dans votre exemple, il s'agit d'une propriété afin que les méthodes "get/set" révèlent que la deuxième option est incorrecte et signifie effectivement "la mise à jour de la mise à jour" et non "Mettre à jour l'emplacement". Mais il est beaucoup trop facile de faire cette erreur, en particulier dans les cas de mots ambigus tels que "mise à jour". Jouer en toute sécurité. Ne confondez pas quelqu'un de nouveau à cela juste pour économiser quelques secondes de votre temps.
/// <summary> Les blocs sont utilisés utilisés pour générer une documentation pour IntelliSense et documentation API .
Ainsi, s'il s'agit d'une API face au public, vous devriez TOUJOURS Incluez au moins un <summary> Commentaire, même si le but de la fonction devrait être Auto-évident aux lecteurs.
Cependant, c'est l'exception à la règle; En général, rappelez-vous simplement de [~ # ~] sec [~ # ~ ~] Ne vous répétez pas).
Ne remplissez comme ça uniquement si Vous savez comment vous bénéficierez de choses comme ça; sinon, essuyez-les.
Pour moi, cas de Avantage clair était quand il y avait une vérification automatisée des commentaires manquants et J'utilisais ce chèque détecter le code lorsque des informations importantes doivent être remplies; Pour cela, je remplissais effectivement quelques Installations - Juste pour vous assurer que le rapport d'outil ne contient pas de "fausses alarmes".
Je pense qu'il y a toujours un moyen de éviter la duplication flagrante. Au fil des ans, je suis venu à utiliser des "charges de modèle" de couple pour des cas comme la vôtre - surtout comme nom auto-descriptif et voir ci-dessus.
Pour cet exemple particulier, j'utiliserais quelque chose de "type auto-descriptif" (en supposant que ce n'est pas le cas où l'essuyage ferait le travail), comme ça:
class Example
{
/// <summary>
/// Self descriptive method name.
/// </summary>
public Uri UpdateLocation { get; set; };
}
Exemple Lorsque je pourrais utiliser voir ci-dessus Boney Fillers serait Javadoc Commentaires nécessitant des champs dédiés pour la valeur de retour, les paramètres et les exceptions. Très souvent, je trouve qu'il est préférable de décrire la plupart ou même tous ceux-ci en une phrase sommaire unique, méthode qui renvoie <décrit ce qui est retourné> pour les paramètres fournis <Paramètres>. Dans des cas comme celui-ci, je remplis des champs formellement obligatoires avec plaine voir ci-dessus, directeur du lecteur à la description sommaire.
Voici une question que j'aime me poser de me poser quand on pense s'il faut ajouter un commentaire dans une section de code: que puis-je transmettre cela aiderait la prochaine personne à comprendre l'ensemble intention du code, de sorte que Ils peuvent mettre à jour, fixer ou l'étendre plus rapidement et plus de manière fiable?
Parfois, la bonne réponse à cette question est que vous ne pouvez rien ajouter à ce moment-là dans le 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 un code auto-documentant solide et que l'insérant un commentaire, il y aurait probablement nuire à plus que ce serait l'aide. (Notez que les commentaires redondants peuvent réellement endommager la fiabilité du code au fil du temps en ralentissant la chute de la synchronisation avec le code réel au fil du temps et rendant ainsi plus difficile à déchiffrer l'intention réelle.
Cependant, dans presque tous les programmes et dans tout langage de programmation, vous allez rencontrer des points où certains concepts critiques et décisions prises par le programmeur d'origine - par vous - ne seront plus apparents dans le code. C'est à peu près inévitable car un bon programmeur toujours Programmes pour l'avenir - c'est-à-dire que non seulement pour faire fonctionner le programme une fois, mais pour faire tous ses nombreux futurs correctifs et versions et modifications et modifications. et des ports et qui sait quoi aussi Travailler correctement. Ce dernier ensemble d'objectifs est beaucoup plus difficile et nécessite beaucoup plus de penser à bien faire. Il est également très difficile d'exprimer bien dans la plupart des langues informatiques, qui sont plus axées sur la fonctionnalité - c'est-à-dire en disant de quoi this version du programme doit faire, en ce moment, afin de rendre cela satisfaisant.
Voici un exemple simple de ce que je veux dire. Dans la plupart des langues, une recherche quadruple en ligne d'une petite structure de données aura suffisamment de complexité que quelqu'un l'examine pour la première fois probablement ne sera probablement pas reconnu immédiatement ce qu'il est. C'est une opportunité pour un bon commentaire, car vous pouvez ajouter quelque chose à propos de Intention de votre code qu'un lecteur ultérieur appréciera probablement immédiatement comme utile pour déchiffrer les détails.
Inversement, dans des langues telles que la langue de la logique, prolog, exprimant la recherche d'une petite liste peut être aussi incroyablement triviale et succincte que tout commentaire que vous pourriez ajouter serait simplement du bruit. Donc, bon commentaire est nécessairement dépendant du contexte. Cela inclut des facteurs tels que les atouts de la langue que vous utilisez et le contexte général du programme.
L'essentiel est-ce: pensez à l'avenir. Demandez-vous ce qui est important et évident pour vous sur la manière dont le programme doit être compris et modifié à l'avenir. [1]
Pour les parties de votre code qui sont vraiment auto-documentant, les commentaires ajoutent simplement du bruit et augmentent le problème de la cohérence des versions futures. Alors ne les ajoute pas là-bas.
Mais pour ces parties de votre code où vous avez pris une décision critique de plusieurs options, ou lorsque le code lui-même est suffisamment complexe que son objectif est obscur, s'il vous plaît, ajoutez vos connaissances spéciales sous la forme d'un commentaire. Un bon commentaire dans une telle affaire est un tel cas qui permet à un futur programmeur savoir ce qui doit être tenu de la même chose - c'est le concept d'affirmation invariante, incidemment - et qu'est-ce qui va changer.
[1] Cela va au-delà de la question des commentaires, mais cela vaut la peine de mentionner: si vous constatez que vous avez une idée très nette de la manière dont votre code pourrait changer à l'avenir, vous devriez probablement penser à faire un commentaire et incorporer ces paramètres Dans le code lui-même, comme cela sera presque toujours un moyen plus fiable d'assurer la fiabilité des futures versions de votre code que d'essayer d'utiliser des commentaires pour diriger une personne inconnue dans la bonne direction. Dans le même temps, vous souhaitez également éviter de se généraliser, car les humains sont notoirement mauvais pour prédire l'avenir, ce qui inclut l'avenir des changements de programme. Essayez donc de définir et de capturer des dimensions d'avenir raisonnables et bien prouvées à tous les niveaux de la conception du programme, mais ne vous laissez pas vous empêcher d'exercer une exercice dans une généralisation excessive qui est peu susceptible de payer à long terme.
Dans mon propre code, je laisserai fréquemment des commentaires Tautologies en place, y compris les particulièrement flagrants comme:
<?php
// return the result
return $result;
?>
... qui contribuent évidemment peu en termes de rendre le code plus compréhensible d'une perspective explicative.
Dans mon esprit, ces commentaires ont toujours de la valeur, s'ils aident à maintenir la cohérence visuelle des modèles de couleur de votre syntaxe surligneur.
Je pense au code comme ayant 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 consister entièrement d'une seule "phrase"). J'inclus généralement une rupture 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;
?>
(Ignorer le code incomplet, les injections SQL, etc. Vous obtenez l'idée.)
Pour moi, le dernier commentaire ajoute de manière véritablement 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 faire une des opérations suivantes.
- Renseignements pour les producteurs de documents à saisir. Cela ne peut pas être sous-estimée, ce qui est extrêmement importante.
- Avertissements pour lesquelles un morceau de code est la façon dont il est, et quelles autres considérations. J'ai eu affaire avec le code écrit en 2 langues de programmation. Une partie clé de c'était d'avoir une structure commune entre les deux langues. Un commentaire sur les deux sites informant l'utilisateur que s'ils changent ce nombre, ils ont aussi besoin de changer une autre est extrêmement utile.
- Notes Ecrire à expliquer pourquoi une recherche particulièrement étrange morceau de code est la façon dont il est. Si vous deviez penser à la façon d'obtenir un morceau de code au travail d'une manière particulière, et la solution est évidente dès le début, il vaut probablement la peine une explication quant à ce que vous essayez de faire.
- Entrées/sorties étiquetage, si elles ne sont pas claires. Il est toujours bon de savoir ce que vos entrées devraient être, et quel format ils sont.
Les commentaires ne doivent pas être utilisés pour effectuer les opérations suivantes:
- Expliquer les choses qui sont extrêmement évidentes. J'ai vu le code existant comme ceci:
page=0; // Sets the page to 0. Je pense que toute personne compétente pourrait comprendre.
Je supprimerais la tautologie mais gardez le commentaire, je voudrais commenter les propriétés et les noms de variables en donnant une valeur de l'échantillon, de sorte que l'utilisation soit clairement comprise:
property UpdateLocation:TUpdateLocation; // url="http://x/y/3.2/upd.aspx",proto=http
Maintenant, je sais exactement ce qui va là-bas et, depuis le commentaire, j'ai une idée claire comment l'utiliser.
Un commentaire comme ça est inutile; Qu'est-ce que je fais mal?
Cela ne semble que si vous savez déjà ce que UpdateLocation fait. "Mise à jour" est-elle ici un verbe ou un nom enjolch? C'est-à-dire que ceci est quelque chose qui met à jour l'emplacement ou est-ce l'emplacement de la mise à jour? On pourrait déduire ce dernier du fait que UpdateLocation est apparemment une propriété, mais le point plus large est que parfois cela ne fait pas mal d'énoncer explicitement quelque chose qui semble évident.
Documentation automatiquement compilée de côté, le code devrait documenter lui-même, de sorte que les commentaires ne devraient documenter que lorsque le code ne suffit pas pour documenter lui-même.
Je pense que ce sujet a été discuté assez largement sous des noms tels que "Commentaires: anti-motifs" ou "sont des commentaires une odeur de code?" ( n exemple ).
J'ai tendance à être d'accord avec l'idée générale que les commentaires devraient ajouter de nouvelles informations, et non dupliquer. En ajoutant des commentaires triviaux comme ça, vous enfreignez le sèche et en diminuant le rapport signal sur bruit du code. J'ai tendance à trouver des commentaires de haut niveau expliquant les responsabilités, justification de la base et l'utilisation de la classe beaucoup plus utile que les commentaires permitoires (en particulier superflus).
Personnellement, dans votre exemple, je laisserais commenter (s'il n'y a vraiment rien d'utile pour ajouter la propriété).
Si vous pouvez écrire du code qui ne nécessite pas de commentaires, vous avez obtenu la programmation Nirvana !.
Le moins de commentaires de votre code nécessite meilleure le code!