Écrire des commentaires à l'intérieur des méthodes n'est-il pas une bonne pratique?
Un ami m'a dit qu'écrire des commentaires à l'intérieur des méthodes n'était pas bon. Il a dit que nous devrions avoir des commentaires uniquement pour les définitions de méthode (javadocs) mais pas à l'intérieur du corps de la méthode. Il semble qu'il ait lu dans un livre qu'avoir des commentaires à l'intérieur du code signifie qu'il y a un problème dans le code. Je ne comprends pas très bien son raisonnement. Je pense que l'écriture de commentaires à l'intérieur du corps de la méthode est bonne et qu'elle aide les autres développeurs à mieux la comprendre et plus rapidement. Veuillez fournir vos commentaires.
Votre ami a tort et très peu de programmeurs seraient d'accord avec lui. Vous devriez écrire des commentaires quand et où vous pensez qu'ils aident le mieux à comprendre.
Ignorez votre ami. Commentez au besoin. Mais essayez de rendre votre code explicite, de sorte que les commentaires ne soient pas nécessaires. N'oubliez pas que votre ordinateur n'exécute pas de commentaires et qu'il est donc facile pour les commentaires de se désynchroniser de ce qui se passe réellement.
J'ai tendance à utiliser un bloc de commentaires pour expliquer une logique particulièrement délicate, qui autrement prendrait un peu de cerveau à lire. Et puis je vais essayer de rendre la logique plus claire et de supprimer le besoin d'explication.
Un bon code est auto-documenté. Une méthode doit faire exactement une chose, et cette chose doit être évidente par le nom de la méthode et les spécifications de commentaire. Par conséquent, le fait d'avoir besoin de commentaires dans la méthode expliquant la logique suggère que la méthode devrait être divisée en méthodes à responsabilité unique.
Maintenant, pour la réalité. Vous êtes confronté à une base de code complexe à code spaghetti et vous essayez d'être gentil avec les responsables. Vous n'avez pas le temps ni le mandat de refactoriser 8 millions de lignes de code, et même si vous le faisiez, il y aurait des nuances car tout est complexe. Que faire?
Je suis surpris du nombre de personnes en désaccord avec ce point de vue.
- Un bon code doit être auto-documenté, vous devez donc choisir soigneusement les noms de méthode, les noms de variables, etc.
- Votre méthode ne doit pas être si longue que vous ne pouvez pas voir la méthode entière et les commentaires sur un seul écran
Cela dit, il y a des exceptions. Mais ce sont des exceptions. Et le point avec les exceptions, c'est qu'elles sont peu nombreuses. Vous n'avez vraiment besoin d'expliquer le code en ligne que si vous faites quelque chose de contre-intuitif.
Une situation typique où vous pourriez avoir besoin de commentaires dans votre méthode est lorsque vous appliquez un hack local pour optimiser la vitesse, mais qui en première lecture peut donner un moment wtf à un autre programmeur. C'est un bon point pour ajouter un commentaire.
Mais en général: non, n'ajoutez pas de commentaires dans vos méthodes.
Je pense qu'il parle d'un cas comme celui-ci:
public void upload() {
// destination Host
String Host = ....
}
Où vous pourriez améliorer le code en ayant un nom de variable plus explicite, plutôt que le commentaire:
public void upload() {
String destinationHost = ....
}
Je crois que votre ami fait référence au "Code propre" de Robert C. Martin. Cependant, je pense qu'il simplifie un peu la situation. Le livre parle de donner aux méthodes des noms clairs et descriptifs, que nous devrions tous connaître, mais qui ne peuvent jamais être répétés suffisamment. Le livre recommande également de rendre les méthodes très petites en encapsulant tout bloc de code auquel on peut donner un nom clair et descriptif dans une méthode qui lui est propre. Donc, si vous pensez qu'un bloc de code a besoin d'un commentaire expliquant ce qu'il fait, vous devez en faire une méthode distincte avec un nom approprié. En théorie, si toutes vos méthodes sont sous 5 lignes, et si elles ont toutes de bons noms descriptifs, il devrait être évident ce qu'elles font sans avoir à l'expliquer dans un commentaire.
Cependant, cela ne signifie pas que vous ne devriez jamais avoir de commentaires dans vos méthodes. Le fait est que les commentaires ne doivent pas être redondants. Ils devraient ajouter des informations. Si vous avez une méthode qui fait exactement une chose, et cette chose est évidente par son nom, alors vous n'avez pas besoin d'un commentaire expliquant ce qu'elle fait. Cependant, il est parfaitement logique d'avoir un commentaire expliquant pourquoi il fait sa chose de cette manière particulière. Vous souhaiterez peut-être un commentaire expliquant pourquoi vous avez choisi un algorithme plutôt qu'un autre, ou pourquoi vous avez choisi une structure de données plutôt qu'une autre. En d'autres termes, vous voulez que le code lui-même explique comment il fonctionne, et vous voulez que les commentaires expliquent les raisons de vos décisions de conception, i. e. pourquoi les choses se font de cette façon particulière.
Le livre recommande de refactoriser le mauvais code au lieu de le commenter. C'est certainement une excellente idée en théorie, mais en réalité, vous n'avez peut-être pas le temps ou l'infrastructure, comme un cadre de test unitaire de travail avec l'ensemble approprié de tests unitaires pour le faire. Il y a des moments où vous êtes confronté à une base de code en désordre, dont vous avez besoin pour travailler hier, et la seule façon d'aller de l'avant est d'essayer de comprendre les éléments en désordre et de les commenter afin de prendre des notes pour vous-même.
Oui, vous écrivez certainement des commentaires à l'intérieur des méthodes en Java.
Comme convention de code de Sun dit:
Les programmes Java peuvent avoir deux types de commentaires: les commentaires d'implémentation et les commentaires de documentation. Les commentaires d'implémentation sont ceux trouvés en C++, délimités par
/*...*/, et//. Les commentaires de documentation (appelés "commentaires de doc") sont uniquement Java et sont délimités par/**...*/. Les commentaires de doc peuvent être extraits dans des fichiers HTML à l'aide de l'outil javadoc.
Ainsi, les commentaires dans les méthodes sont des commentaires d'implémentation.
Je suis fortement en désaccord avec votre ami et soutiens que les commentaires sur la fonction en ligne sont une partie très importante de l'écriture d'un bon code. Les commentaires de fonction sont conçus pour donner aux clients du code une meilleure compréhension de ce que le code est censé faire - ce que signifient ses paramètres et valeurs de retour, les types d'invariants qu'il s'attend à avoir à l'entrée et à la sortie, etc. s'adressent principalement aux responsables du code et idéalement comme une série de notes mentales pour l'auteur original du code. Ils permettent de regarder une méthode complexe qu'une autre personne a lue et de comprendre ce que pensait l'auteur d'origine. Ils facilitent également le diagnostic des bogues, car si les commentaires décrivent l'intention du code et les hypothèses qu'il fait, il peut être beaucoup plus facile de comprendre comment un morceau de code est erroné lorsqu'un dysfonctionnement est détecté.
Personnellement, je trouve les commentaires en ligne utiles car ils me forcent à me prouver que le code que je vais écrire va fonctionner correctement. Souvent, je prendrai l'habitude de ne pas écrire de code sans d'abord clairement commenter l'intention et comment cela va fonctionner. Plus souvent qu'autrement, cela m'empêche de faire des erreurs stupides dans le code parce que je trouverai que mon explication est incorrecte ou ne prend pas en compte certains cas Edge.
Bien sûr, chacun a sa propre discipline de codage, et certaines personnes trouvent peut-être plus facile d'écrire du code sans commentaires en ligne et de diviser le code en plusieurs méthodes plus petites. Cependant, par expérience, j'ai trouvé que les commentaires en ligne sont inestimables pendant le développement et le débogage, et extrêmement utiles pour d'autres personnes qui doivent parcourir et maintenir mon code longtemps après que je suis passé à un autre projet.
Votre ami pourrait bien exprimer l'idée que les commentaires sont, sinon eux-mêmes une "odeur de code", un " déodorant ". Ce n'est pas spécifique aux commentaires dans la méthode, mais cela peut avoir tendance à être plus vrai des commentaires dans la méthode que des commentaires du préambule.
Lorsque vous écrivez un commentaire, c'est généralement pour expliquer quelque chose. Quand quelque chose doit être expliqué - eh bien, ce n'est pas explicite. Le bon code est auto-explicatif. Ainsi, lorsque vous ajoutez des commentaires, vous masquez son échec à s'expliquer sans le rendre explicite. Donc, chaque fois que vous écrivez un commentaire comme ça, au lieu de changer le code - en renommant, par extraction de méthode, etc. - en faites-le explicite, vous êtes loin de l'idéal.
Mais nous manquons tous de temps en temps de perfection. Et il est souvent préférable d'ajouter un commentaire explicatif que de laisser du code difficile à comprendre sans document.
De bons commentaires expliquent le pourquoi pas le comment. Telle est la principale distinction ici. La plupart des gens seront en mesure de suivre ce que vous faites, mais pourquoi vous l'avez fait nécessite des commentaires supplémentaires. Ces commentaires devraient être aussi proches que possible de l'opération.
Lorsque vous commentez votre code (ou le code vraiment mal documenté de quelqu'un d'autre), vous pouvez souvent être confronté à des sentiments de dégoût pur de dégoût , haine ou colère . Le code peut se comporter de manière frustrante et inattendue et vous devrez peut-être ajouter des hacks très maléfiques pour le faire fonctionner pour une certaine date limite.
Dans tous ces cas, exprimer vos sentiments en annotant les portions respectives de code avec des jurons lourds (voir fuckcount du noyau linux ) est une pratique courante. Ces commentaires doivent vivre dans les méthodes afin qu'ils n'apparaissent pas dans l'API auto-documentée, donc ni votre patron ni vos clients ni aucune autre personne agnostique de code source ne le verra jamais.
Vos collègues programmeurs se sentiront cependant très bien soulagement et bonheur lors de l'étude de la source . (Et bien sûr, vous pouvez vous ajouter des notes ou utiliser le code source comme moyen de communication dans une certaine mesure, #TODO: add more examples here)
Bien sûr, vous pourriez faire valoir que ces types de commentaires ne sont pas censés être là en premier lieu, ou qu'ils devraient être supprimés avant la version finale, mais de nos jours, les projets logiciels ont des cycles de publication très courts, et certains commentaires sont toujours pertinents de nombreuses versions nocturnes plus tard, alors votre ami devrait peut-être commencer à apprendre à lire (et écrire) entre les lignes .
C'est bien d'avoir du code qui n'a pas besoin de commenter. Lorsque vous obtenez, enregistrez et supprimez des éléments, nous avons une assez bonne idée de ce qui se passe et n'avons pas besoin de commentaires.
Parfois, le code devient désordonné et est un candidat pour la refactorisation, vous devrez donc peut-être commenter dans l'intervalle.
Aujourd'hui, j'avais une ligne de code pour ne pas faire ce qui était attendu. Apparemment, une table de données .net ne pense pas qu'une ligne importée est un nouvel enregistrement. Lorsque vous insérez les enregistrements de la table, rien ne se produit. Le statut de la ligne importée doit d'abord être modifié. Un simple commentaire suffit, alors quand j'y reviens dans 6 mois et que je me dis: "Pourquoi diable ai-je besoin de ça?" Je saurai.
Il est courant pour les programmeurs de mettre des commentaires à l'intérieur des méthodes chaque fois qu'ils pensent qu'il n'est pas clair pour les autres programmeurs ce que fait le code. Les programmeurs mettent parfois des commentaires TODO à l'intérieur de la méthode. Cependant, il est vrai que si vous avez trop de commentaires dans les méthodes, vous devrez peut-être prendre du recul et penser si vous faites des choses trop compliquées qu'elles ne devraient l'être. Dans d'autres Word, vous voudrez probablement éviter de commenter quelque chose d'évident pour les autres programmeurs car il est plus difficile de lire le code avec eux.
Pour prendre positivement la suggestion de vos amis, vous devez vous rappeler que nous pouvons éviter de trop commenter en nommant correctement les variables et les méthodes et garder chaque méthode petite et nous assurer qu'elle ne fait pas trop de personnel.
Je pense que la raison pour laquelle il a dit cela est parce qu'il pense que les fonctions devraient être suffisamment courtes pour que chacune n'encapsule qu'une seule opération conceptuelle.
Je ne souscris pas nécessairement à cette croyance à son extrême (pour diverses raisons, notamment que la lecture d'un tel code peut devenir un cauchemar), mais si tel était le cas, il pourrait en résulter qu'ils n'auraient qu'un seul commentaire par fonction, car il n'y a que un concept par fonction et un commentaire par concept.
Quoi qu'il en soit, j'utilise des commentaires chaque fois et partout où il y a du code dont le choix ou le comportement n'est pas immédiatement évident - souvent lié à des considérations de performances ou à des calculs ésotériques. Ce genre de choses ne concerne souvent pas immédiatement le consommateur de la fonction, donc je dirais que c'est en fait une bonne idée de le cacher de la documentation.
Je crois que votre ami parlait de javadoc, qui générera de la documentation à partir de votre commentaire s'il est au-dessus de votre déclaration de méthode (et décoré d'un astérisque supplémentaire) comme ceci:
/**
get a webpage for a given url
@param url: the url to get
@returns String: the http-source
*/
public String getWebpage (String url) {
...
Si vous mettez ce commentaire dans la méthode, il est inutile.
Par conséquent - en règle générale: mettez des commentaires dans Java source au-dessus de la méthode.
Des exceptions peuvent et vont se produire. J'accepte: d'utiliser des méthodes courtes, d'écrire du code auto-documenté. Cependant javadoc en tant qu'outil encourage la duplication des commentaires, car sinon il semble si nu dans la documentation. :)
Je concède le point que dans une méthode écrite à partir de zéro, on pourrait documenter sa fonction dans l'en-tête uniquement. Toutefois.
Je trouve que des commentaires sont souvent insérés là où des bogues ont été découverts et qu'une nuance subtile a été négligée même si la méthode n'a qu'une seule responsabilité - ce qui, soyons honnêtes, est rarement le cas dans le code hérité. De plus, je ne vois aucune raison d'avoir un nom de variable de quarante caractères (même s'il n'est utilisé qu'à deux endroits) quand un nom de variable plus court avec un commentaire succinct peut être plus facilement digéré et réutilisé plus tard. Propre et concis est le meilleur, mais surtout, c'est un moyen de communication avec les autres programmeurs autant que les e-mails, les lettres et la poésie. Et à cela j'ajoute la citation:
"Je n'ai fait que rallonger cette lettre parce que je n'ai pas eu le temps de la raccourcir."
Blaise Pascal, (1623-1662) Lettres provinciales
Les commentaires ne font que rendre le code plus convivial pour le programmeur, n'oubliez pas que les commentaires ne seront pas exécutés.
Si vous deviez lire votre code après quelques mois, les commentaires faciliteront la lecture du code.
Cela rendra le code maintenable et tout autre programmeur qui regarde le code trouvera facile de comprendre la logique que vous avez implémentée.
Cela ne signifie pas que vous devez toujours ajouter des commentaires, même pour une méthode avec quelques lignes de code.
Comme par exemple, le code suivant est explicite et ne nécessite aucun commentaire pour rendre sa fonction claire
public String getName(){
return name;
}
Alors que lorsqu'une méthode est volumineuse, ajoutez un commentaire afin qu'il soit plus lisible chaque fois qu'un programmeur la regarde.
Rappelez-vous que lors du codage, vous pourriez penser que le code est explicite, mais lorsque vous pouvez le consulter après six mois, les commentaires que vous avez ajoutés il y a six mois vous aideront certainement, vous ou tout autre programmeur, à comprendre le code rapidement.
Le problème avec les commentaires en ligne est qu'ils doivent être maintenus avec le code (également vrai pour les commentaires au niveau de la fonction/méthode/module/classe, mais pas autant); Dieu sait combien de code source est encore là où les commentaires n'ont plus rien à voir avec le code qu'ils documentent, ce que l'OMI est tout aussi mauvais ou pire que de ne pas avoir de commentaires du tout.
Idéalement, la documentation en ligne devrait être limitée aux situations suivantes:
Expliquer le code fortement optimisé ou "délicat", ainsi qu'une justification de pourquoi le code est tellement fortement optimisé ou "délicat" ("nous manquions l'exigence de performances X et le profilage a montré que le goulot d'étranglement se trouvait dans ce section; les optimisations ci-dessous ont gagné des performances en% ");
Se référant à une norme ou à une exigence ("L'espacement des postes DTED 0 est de 30 secondes d'arc");
Identifier le code qui nécessite une analyse/développement supplémentaire ("TODO");
Première loi de la docmentation de code - ne documentez pas l'évidence. Corollaire de la première loi de la documentation du code - écrivez le code le plus évident possible.
Premièrement, votre question était spécifiquement orientée Java - ce qui influence considérablement la réponse.
La quantité de commentaires obligatoire est fortement liée à la langue dans laquelle vous travaillez.
Certains langages tels que Java et C # se prêtent très bien au concept de code auto-documenté. Dans ces langages, il est préférable de consacrer vos efforts à rendre le code lui-même aussi lisible et descriptif que possible, et puis en ajoutant des commentaires en ligne uniquement pour les choses que vous ne pouvez pas décrire nativement dans la langue.
Certains langages tels que SQL sont plus difficiles à rendre lisibles. La syntaxe, l'ordre d'évaluation, l'imbrication, etc. peuvent rendre plus difficile la conception d'une manière auto-documentée. La même approche de base s'applique toujours: concentrez-vous sur l'utilisation de la langue autant que possible, puis ajoutez des commentaires pour compenser les zones peu claires ou déroutantes.
Dans l'ensemble, vous ne pouvez pas supprimer à 100% les commentaires, mais votre objectif devrait être de supprimer le besoin pour les commentaires autant que possible en rendant le code plus auto-descriptif. Les résultats de ces efforts sont généralement moins de code global et un code mieux organisé. Indépendamment de la présence ou non de commentaires, cela signifie que votre code sera beaucoup plus facile à gérer et accessible - c'est vraiment ce que les commentaires sont censés aider à tous égards.
L'idée que Javadoc (ou même des astuces de saisie semi-automatique Delphi) devrait changer la façon dont une personne code (autre que d'ajouter des fonctionnalités pour javadoc) est assez absurde.
Demandez à votre ami qui est venu en premier, le javac ou le javadoc?
C'est comme demander qui est venu en premier, la vache ou Mme O'Leary
De plus, javadoc devrait être destiné aux personnes implémentant votre classe et vos fonctions, les commentaires dans le code sont destinés aux personnes qui gèrent votre code. Surtout avec vos méthodes privées, personne ne devrait nécessairement avoir à regarder votre code pour voir ce qu'il fait. C'est à ça que servent les doc. Mais si quelqu'un a besoin de modifier quelque chose à cause d'une erreur poilue par une erreur, vous souhaitez le commenter dans votre méthode.
Il suppose évidemment que les 90% de code qui sont en fait des corrections de bugs sont tous mauvais. Je n'ai jamais lu "Le programmeur pragmatique" mais je peux supposer qu'il ne fait pas référence à ce livre.
Je vais jeter mes deux cents maintenant que la fête est à peu près terminée. J'utilise des commentaires lorsque je décris un élément spécifique de la logique métier ou lorsque je dois ajouter quelque chose pour couvrir un cas Edge imprévu.
Le code évolue au fil du temps pour tenir compte de choses qui n'étaient pas connues à l'avance, et donc lorsque vous appliquez un pansement, au lieu de supposer qu'il est connu pourquoi vous mettez ce pansement, cela aide parfois pour ajouter un petit bloc dans le code qui dit "oh, au fait, j'ai dû résoudre ce problème et voici la référence bugtracker afin que vous puissiez suivre la conversation environnante" et dans mon cas (comme j'utilise FogBugz), cela ressemblerait à ceci :
//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );
ou peu importe. Donc, mon point est que quelque chose qui semble hors de propos et qui n'est pas aussi lisible est probablement un bon endroit pour intégrer le document. La connaissance collectée est une belle chose.
Mais mon premier point était ma logique commerciale. J'ai littéralement un bloc dans une procédure stockée que je suis sur le point de réécrire cet AM qui a quelques règles métier à l'avant.
/****************************************************************
author yourstruly
date 2010-11-18
descrip intended use is to blah blah blah
ended up over actual measured blah blah blah according to blah blah blah
rules from the customer are:
If the sum of the blah blah blah is higher than the blah blah blah
and the blah blah blah contain blah blah blah,
and the blah blah blah is non-zero,
recalculate the blah blah blah to fit within the blah blah blah
Additional rules for us internally:
if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)
rewritten here with (1) traceable statements for the where clauses.
If
the blah blah blah(1) is higher than the blah blah blah (2)
and the blah blah blah (3)
and the blah blah blah is non-zero (9)
and the blah blah blah is lower than the blah blah blah (4)
and the edited blah blah blah is higher than the blah blah blah (5)
then recalculate the blah blah blah (6)
// See note lower in this document on the math
If
the blah blah blah(1) is higher than the blah blah blah (2)
and the blah blah blah (3)
and the blah blah blah is higher than the blah blah blah (7)
then set the blah blah blah to zero (8)
(7) dictates the same as (4) but it's easier to do (7)
****************************************************************/
Sorry for the blah blah blah's but proprietary rules and all that ;)
Et tout d'un coup, vous voyez que j'ai des exigences (!) Intégrées dans mon code en tant que commentaires et je peux faire référence aux commentaires comme /*(1)*/ (ce que je fais) afin que cela soit facilement traçable pour le prochain employé (ce qui était le cas, et il a pu trouver les parties qui avaient besoin d'être peaufinées immédiatement) et puis si quelqu'un veut savoir quelle était la spécification, il peut lire le commentaire ci-dessus, et si quelqu'un veut savoir quel est le pseudo-code c'est là et si quelqu'un veut convertir le pseudo-code en code, alors vous y allez. Pour moi, cela est beaucoup plus lisible (pour mon cas) car il préserve la demande d'origine (extrait de l'e-mail) et permet de rassembler rapidement le train de la pensée sans trop de réflexion, et permet d'utiliser des transformations faciles du pseudo en code réel.
Et oui, il y a des commentaires en ligne disant que tel ou tel ne fonctionnait pas comme prévu dans le pseudo-code parce que l'exigence ne correspondait pas tout à fait aux données, nous avions donc besoin de modifier les données. Mais c'est mon point. Nous avons documenté en ligne les cas Edge et nous avons laissé le pseudo-code dans le code approprié pour suivre la logique, donc nous savions tous ce qui était attendu des exigences d'origine.