Un de mes collègues estime que toute utilisation de commentaires dans le code (c.-à-d. Sans méthode de style javadoc ni commentaires de classe) est une odeur de code . Qu'est-ce que tu penses?
comments
anti-patterns
Fishtoaster
la source
la source
Réponses:
Seulement si le commentaire décrit ce que fait le code.
Si je voulais savoir ce qui se passait dans une méthode ou un bloc, je lisais le code. J'espère de toute façon que tous les développeurs travaillant sur un projet donné sont au moins suffisamment familiarisés avec le langage de développement pour lire ce qui est écrit et comprendre ce qu'il fait.
Dans certains cas d'optimisation extrême, vous pouvez utiliser des techniques qui rendent difficile la tâche de suivre ce que votre code est en train de faire. Dans ces cas, les commentaires peuvent et doivent être utilisés non seulement pour expliquer pourquoi vous avez de telles optimisations, mais également pour ce que fait le code. En règle générale, demandez à une autre personne (ou à plusieurs autres personnes) de connaître le langage et le projet d’implémentation et examinez votre code - si elle ne comprend pas à la fois le pourquoi et le comment, vous devez commenter le pourquoi et le le comment
Cependant, ce qui n'est pas clair dans le code, c'est pourquoi vous avez fait quelque chose. Si vous adoptez une approche qui pourrait ne pas être évidente pour les autres, vous devriez avoir un commentaire expliquant pourquoi vous avez pris les décisions que vous avez prises. J'imagine que vous ne réaliserez peut-être même pas qu'un commentaire est nécessaire avant quelque chose comme une révision de code, où les gens veulent savoir pourquoi vous avez fait X au lieu de Y - vous pouvez capturer votre réponse dans le code pour tous ceux qui l'examinent. A l'avenir.
La chose la plus importante, cependant, est de modifier vos commentaires lorsque vous modifiez votre code. Si vous modifiez un algorithme, veillez à mettre à jour les commentaires en indiquant pourquoi vous avez opté pour l'algorithme X sur Y. Les commentaires obsolètes dégagent une odeur de code encore plus grande.
la source
Ceci est particulièrement irritant à entendre pour le moment. J'ai passé quelque temps ce week-end à regarder du code très bien nommé, très propre et sans commentaire implémentant un algorithme de recherche (un algorithme qui n'est pas réellement publié). Je suis au courant de cela, le gars assis à côté de moi était l'inventeur, et le code a été écrit il y a quelques années par quelqu'un d'autre. Nous pouvions à peine le suivre.
Votre collègue n'est pas assez expérimenté, évidemment.
la source
Les commentaires devraient expliquer pourquoi, pas comment.
How
Les commentaires de type sont généralement mieux traités avec la refactorisation. Personnellement, j'évite généralement les commentaires favorables à la refactorisation.Avant:
après:
la source
Je déclare votre collègue un hérétique! Où sont mes bottes brûlantes hérétiques?
Obsessionnels commentant est mauvais et un mal de tête d'entretien, et les commentaires ne remplacent pas les méthodes bien nommées, des classes, des variables, etc. Mais parfois mettre pourquoi quelque chose est la façon dont il est peut être extrêmement précieux pour l'idiot pauvre qui doit maintenir le code dans six mois - en particulier quand ce pauvre idiot finit par être toi.
Quelques commentaires du code sur lequel je travaille:
la source
SomebodyScrewedAroundWithDatabaseException
...Idéalement, le code devrait être si bien codé qu'il devrait être auto-explicatif. Dans le monde réel, nous savons qu’un code de très haute qualité nécessite parfois des commentaires.
Ce qu'il faut absolument éviter, c'est la "redondance des commentaires" (commentaires qui n'ajoutent rien au code):
Ensuite, s’il existe une bonne conception du code (et maintenu / aligné), les commentaires sont encore moins utiles.
Mais dans certaines circonstances, les commentaires peuvent être une aide précieuse pour la lisibilité du code:
N'oubliez pas que vous devez gérer et synchroniser également les commentaires ... les commentaires obsolètes ou erronés peuvent être une douleur terrible! Et, en règle générale, trop de commentaires peut être le symptôme d'une mauvaise programmation.
la source
} //end while
Cela signifie simplement que le début de la boucle while est si éloigné que vous ne pouvez même pas le voir, et rien ne laisse présager que le code que vous consultez est en boucle. Une refactorisation lourde devrait être sérieusement préférée aux commentaires sur la structure du code.} // end while
commentaires peuvent être une bouée de sauvetage.Définir catégoriquement une méthode ou un processus en tant qu '"odeur de code" est une "odeur de fanatisme". Le terme devient le nouveau "considéré comme nuisible".
S'il vous plaît rappelez-vous que toutes ces choses sont supposées être des directives.
Bon nombre des autres réponses donnent de bons conseils quant au moment où les commentaires sont justifiés.
Personnellement j'utilise très peu de commentaires. Expliquez le but de processus non évidents et laissez la menace de mort occasionnelle à quiconque pourrait envisager de modifier lui-même des choses qui nécessitaient des semaines de réglage.
Refacturer tout jusqu'à ce qu'un enfant d'âge maternelle puisse comprendre que ce n'est probablement pas une utilisation efficace de votre temps et ne fonctionnera probablement pas aussi bien qu'une version plus concise.
Les commentaires n'affectant pas le temps d'exécution, le seul problème à prendre en compte est la maintenance.
la source
Dans certains cas, aucune bonne désignation, refactoring, etc. ne peut remplacer un commentaire. Il suffit de regarder cet exemple du monde réel (la langue est Groovy):
Ça a l'air étrange, n'est-ce pas? Probablement une erreur de copier / coller? Crie pour un bug?
Maintenant la même chose avec les commentaires:
la source
Le problème principal ici est la signification du terme "odeur de code".
De nombreuses personnes (y compris vous, je pense) comprennent qu'une odeur de code ressemble à une erreur ou, du moins, à une correction. Vous pensez peut-être que cela est synonyme d’anti-pattern.
Ce n'est pas le sens du terme!
La métaphore de l'odeur du code provient de Wards Wiki , et ils soulignent:
Alors qu'est-ce que ça veut dire que les commentaires sont une odeur de code: cela signifie que quand vous voyez un commentaire, vous devriez faire une pause et penser: "Hmmm, je sens un indice que quelque chose pourrait être amélioré". Peut-être que vous pouvez renommer une variable, effectuer la méthode "extract method" -refactoring - ou peut-être que le commentaire est en fait la meilleure solution.
C’est ce que cela signifie pour les commentaires d’être des codes qui sentent.
EDIT: Je suis tombé sur ces deux articles, ce qui explique mieux que moi:
la source
Je pense que la règle est assez simple: imaginez un inconnu complet en train de voir votre code. Vous serez probablement étranger à votre propre code dans 5 ans. Essayez de minimiser l'effort mental pour comprendre votre code pour cet étranger.
la source
Une bonne idée pour avoir les bons commentaires est de commencer par écrire des commentaires.
Cela vous permet d'extraire facilement des méthodes pour même vous débarrasser des commentaires,
laissez simplement le code dire ces choses ! Voyez comment cela est réécrit (couper / coller) de manière très agréable:
Pour les choses qui ne peuvent pas être séparées, n'extrayez pas les méthodes et ne tapez pas le code sous les commentaires.
C’est ce que je considère comme un moyen utile de réduire au minimum les commentaires. C’est vraiment inutile de commenter chaque ligne ... Documentez une seule ligne uniquement s’il s’agit d’une initialisation de valeur magique ou lorsque cela a du sens.
Si les paramètres sont trop utilisés, ils doivent alors être des membres privés de votre classe.
la source
Je pense que la réponse est l'habituel "Cela dépend". Commenter le code juste pour commenter le code est une odeur. En commentant le code parce que vous utilisez un algorithme obscur qui est un ordre de grandeur plus rapide, le programmeur de maintenance (généralement six mois après que je l'ai écrit) enregistre une demi-journée de fouille dans le code pour déterminer ce qu'il fait.
la source
ou
la source
Les commentaires de code ne sont certainement pas une "odeur de code". Cette croyance découle généralement du fait que les commentaires peuvent devenir obsolètes (désuets) et difficiles à conserver. Cependant, avoir de bons commentaires expliquant pourquoi le code fait quelque chose d'une certaine manière peut (et est généralement) important pour la maintenance.
la source
Si le code a été écrit d'une manière particulière pour éviter un problème présent dans une bibliothèque (à la fois une bibliothèque tierce ou une bibliothèque fournie avec le compilateur), il est logique de le commenter.
Il est également judicieux de commenter le code devant être modifié dans les versions futures, lors de l’utilisation d’une nouvelle version d’une bibliothèque, ou lors du passage de PHP4 à PHP5, par exemple.
la source
Même le livre le mieux écrit a encore probablement une introduction et des titres de chapitre. Les commentaires dans du code bien documenté sont toujours utiles pour décrire les concepts de haut niveau et expliquer comment le code est organisé.
la source
Une mention honorable est l'anti-pattern:
J'ai l'impression que, parfois, les préamplis de licence FLOSS sont fréquemment utilisés à la place de la documentation de fichier. La GPL / BSDL crée un joli texte de remplissage, et après cela, vous voyez rarement un autre bloc de commentaires.
la source
Je ne suis pas d'accord avec l'idée qu'il est mauvais d'écrire des commentaires pour expliquer le code. Cela ignore complètement le fait que le code contient des bogues. On pourrait voir clairement ce que le code fait sans commentaires. Ce que le code est censé faire est moins clair . Sans commentaires, comment savoir si les résultats sont erronés ou s'ils sont utilisés de manière incorrecte?
Les commentaires doivent expliquer l’ intention du code, de sorte que, s’il ya erreur, une personne qui lit les commentaires + code a une chance de le trouver.
Je me retrouve généralement à écrire des commentaires en ligne avant d’ écrire le code. De cette façon, il est clair que j'essaye d'écrire du code et réduit le risque d'être perdu dans un algorithme sans vraiment savoir ce que vous essayez de faire.
la source
Les commentaires qui ont été ajoutés parce que quelqu'un pense qu'il est acceptable d'avoir 700 lignes dans une méthode sont une odeur.
Les commentaires qui sont là parce que vous savez que si vous ne mettez pas de commentaire, quelqu'un commettra la même erreur encore une fois, ce sera une odeur.
Les commentaires insérés parce que certains outils d'analyse de code l'exigent sont également une odeur.
Les personnes qui n'écriront jamais de commentaires ou n'écriront même pas un petit coup de pouce pour les autres développeurs auront aussi une odeur. Je suis étonné de voir combien de personnes n'écriront rien, mais se retourneront ensuite pour reconnaître qu'elles ne peuvent pas se souvenir de ce qu'elles ont fait il y a trois mois. Je n'aime pas écrire des documents, mais j'aime avoir à dire encore et encore aux gens la même chose encore moins.
la source
Je vais répondre avec une question à moi. Pouvez-vous trouver le bogue dans le code non commenté ci-dessous?
tl; dr: La prochaine personne à entretenir votre code pourrait ne pas être aussi divin que vous.
la source
Vous devez garder un équilibre entre le code et les commentaires ... Habituellement, j'essaie d'ajouter des commentaires qui résument un bloc de code. Non pas parce que je ne pourrai pas comprendre le code (enfin, ça aussi), mais parce que je peux lire plus rapidement mon propre code et localiser des sections spécifiques où se trouve l'essentiel.
Quoi qu'il en soit, mes critères personnels sont "en cas de doute, commentez". Je préfère avoir une ligne redondante qu'une ligne complètement cryptique que je ne pourrai pas comprendre. Je peux toujours supprimer les commentaires sur une révision de code, après un certain temps (et c'est généralement le cas)
En outre, les commentaires sont très utiles en ajoutant des "mises en garde" comme "Faites attention! Si le format de l'entrée n'est pas ASCII, ce code devra changer!"
la source
En lisant ceci, cela me rappelle quelque chose que j’avais lu pour la première fois (d’une liste plus longue, conservée par photocopies) il ya quelques décennies:
Une odeur un peu plus âgée me semble.
la source
Je pense que les commentaires de code ont un très mauvais départ dans la vie. Je ne sais pas à propos de ces jours-ci, mais lorsque l’on m’enseignait la programmation à l’école, j’ai reçu des devoirs du type "Écris un programme qui affiche les nombres de un à dix sur des lignes séparées. Assurez-vous de commenter votre code." Si vous n’ajoutiez pas de commentaires, vous seriez mal notés, car commenter votre code est une bonne chose.
Mais qu'y a-t-il à dire sur un processus aussi trivial? Donc vous finissez par écrire le classique
juste pour obtenir une note décente et, si vous en avez un, vous créez instantanément une très faible opinion des commentaires de code.
Commenter le code n'est pas une bonne chose. C’est quelque chose de nécessaire, et Thomas Owens, dans la réponse au haut de la page, fournit une excellente explication des situations dans lesquelles il est nécessaire. Cependant, ces situations se produisent rarement dans les travaux de type devoirs.
À bien des égards, l'ajout d'un commentaire devrait être considéré comme un choix de dernier recours, lorsque ce qui doit être dit ne peut pas être dit clairement dans les parties actives du langage de programmation. Bien que la dénomination des objets puisse devenir obsolète, divers mécanismes d’absence de retour d’informations (humain et ordinateur) facilitent l’oubli du maintien des commentaires. Par conséquent, les commentaires s’étalent beaucoup plus rapidement que le code actif. Pour cette raison, lorsqu'un choix est possible, il convient de toujours préférer modifier le code pour le rendre plus clair que d'annoter un code peu clair avec des commentaires.
la source
Bien sûr, les commentaires sont une odeur de code ...
chaque programmeur sait que nous finissons tous par devenir fous à cause de la quantité de travail, de débogage ou simplement de la folie que nous rencontrons.
"Fais ça!" dit votre chef de projet.
Vous répondez: "Cela ne peut pas être fait."
Ils disent: "Ensuite, nous trouverons quelqu'un d'autre pour le faire."
Vous dites: "OK, peut-être que cela peut être fait."
Et ensuite, passez X jours, semaines, mois… à essayer de le comprendre. Tout au long du processus, vous allez essayer et échouer, et essayer et échouer. Nous faisons tous cela. La vraie réponse est qu'il y a deux types de programmeurs, ceux qui commentent et ceux qui ne le font pas.
1) Ceux qui le font facilitent leur propre travail en documentant pour référence future, en commentant les routines échouées qui ne fonctionnent pas (l’odeur ne les supprime pas après avoir trouvé celle qui fonctionne.) Ou en rompant le code avec des commentaires. Nous espérons que le formatage le rendra un peu plus facile à lire et à comprendre. Sérieusement, je ne peux pas leur en vouloir. Mais à la fin, ils se cassent et puis vous avez ceci:
// dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2) Ceux qui ne le font pas prétendent être un super-héros ou vivent dans une grotte . Ils ont simplement eux-mêmes un mépris inconsidéré pour les autres et se moquent bien du code ou de la signification que cela pourrait avoir pour plus tard.
Maintenant, ne vous méprenez pas… les variables et les fonctions auto-documentées peuvent éviter ce problème… et croyez-moi, vous ne pourrez jamais nettoyer suffisamment de code. Mais la vérité est que tant que vous conservez des sauvegardes, vous pouvez TOUJOURS supprimer des commentaires.
la source
Je dirais que ne pas utiliser certains commentaires dans votre code est une odeur de code. Bien que je convienne que le code doit être auto-documenté autant que possible, vous atteignez un certain point où vous allez voir du code qui n'a aucun sens, quelle que soit la qualité de l'écriture du code. J'ai vu du code dans des applications métier où les commentaires sont à peu près obligatoires car:
En outre, les guides de style de l'entreprise peuvent vous indiquer de faire quelque chose d'une certaine manière. S'ils disent que vous pourriez avoir des commentaires décrivant les blocs de code d'une fonction, incluez-les.
la source
Il existe une grande différence fondamentale entre les commentaires et le code: les commentaires sont un moyen pour les personnes de communiquer des idées à d'autres personnes, alors que le code est principalement destiné à l'ordinateur. Le "code" comporte de nombreux aspects qui ne concernent que les humains, comme la dénomination et l'indentation. Mais les commentaires sont écrits strictement pour les humains, par les humains.
Par conséquent, écrire des commentaires est aussi difficile que toute communication humaine écrite! L’écrivain doit avoir une idée claire de l’audience et du type de texte dont il aura besoin. Comment savoir qui lira vos commentaires dans dix ou vingt ans? Et si la personne est d'une culture complètement différente? Etc. J'espère que tout le monde comprend cela.
Même à l'intérieur de la petite culture homogène dans laquelle je vis, il est tellement difficile de communiquer des idées à d'autres personnes. La communication humaine échoue généralement, sauf par accident.
la source
Je suis d'accord avec votre collègue. Je dis toujours que si je commente mon code, cela signifie que je suis inquiet que je ne serai pas en mesure de comprendre mon propre code à l'avenir. C'est un mauvais signe.
La seule autre raison pour laquelle j'ajoute des commentaires dans le code est d'appeler quelque chose qui n'a pas de sens.
Ces commentaires prennent généralement la forme de quelque chose comme:
ou
la source
Les commentaires de code donnant, le cas échéant, des unités d’arguments et de retours de fonction, des champs de structure, même des variables locales, peuvent s’avérer très utiles. Rappelez-vous l'orbiteur de Mars!
la source
Voici ma règle d'or:
la source
Renseignez votre collègue sur la technique de programmation alphabète .
la source
Non, les commentaires ne sont pas une odeur de code, ils sont simplement un outil qui peut être utilisé de manière abusive.
Exemples de bons commentaires:
// Je pense que c'est en cm. Une enquête plus approfondie est nécessaire!
// C'est une façon intelligente de faire X
// La liste est garantie d'être non vide ici
la source
Assert(list.IsEmpty)
?Assert(!list.isEmpty())
n'est pas exactement un contrat comme dans le troisième commentaire, mais simplement un comportement (c'est-à-dire "lève une exception IllegalArgumentException si l'argument est vide") qui doit être testé par unité, comme toute autre logique de programme. Notez la différence subtile avec le commentaire, qui indique quand la méthode peut être utilisée, mais ne spécifie aucun comportement si la condition préalable n'est pas remplie. Même mieux que le commentaire serait de faire respecter les contrats de compilation. Mais cela dépasse le cadre de ma réponse;)Assert
s, car ils décrivent des choses qui ne devraient jamais se produire, même si l'API publique reçoit des arguments non valides.