Norme de codage pour plus de clarté: commentez chaque ligne de code?
J'ai travaillé dans des magasins qui produisent des logiciels vitaux et j'ai traité des règles de commentaire qui étaient censées garder le code lisible et potentiellement sauver des vies. D'après mon expérience, bien que l'exigence devienne une corvée mortelle à cocher d'une liste de contrôle et ne m'aide pas à rester concentré sur l'écriture de code compréhensible. Cela empêche également mon pair réviseur d'avoir une conversation plus significative avec moi sur la façon de rendre le code plus facile à comprendre.
J'ai également noté le code étudiant qui n'a fait aucun commentaire et j'ai vu pourquoi il fallait le noter pour les avoir négligés.
Je comprends que l'utilisation de bons noms, la simplicité des structures, les fonctions courtes et les modules concentrés garderont le code suffisamment compréhensible pour que les commentaires puissent être minimisés.
Je comprends également que les commentaires devraient expliquer pourquoi le code fait ce qu'il fait, pas comment.
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée? Ceux qui seront pertinents dans un examen par les pairs mais ne se transformeront pas en une activité de liste de contrôle stupide qui ne produit pas de notes plus utiles que: "Vous avez oublié de commenter à la ligne 42".
Un exemple du type de code que cette règle peut nécessiter lorsqu'elle est traitée comme une ligne dans une liste de contrôle:
/* Display an error message */
function display_error_message( $error_message )
{
/* Display the error message */
echo $error_message;
/* Exit the application */
exit();
}
/* -------------------------------------------------------------------- */
/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
/* Display an error message */
display_error_message( 'Error: Configuration file not found. Application has stopped');
}
S'il est possible de l'exprimer correctement dans un document de normes, et que ce n'est tout simplement pas le cas, je voudrais saisir une idée dans ce sens:
Considérez un commentaire pour chaque ligne, séquence, instruction, section, structure, fonction, méthode, classe, package, composant, ... du code. Envisagez ensuite de renommer et de simplifier pour éliminer tout besoin de ce commentaire afin de pouvoir le supprimer. Enregistrez-vous alors que les commentaires sont rares. Répétez jusqu'à la date limite. Puis répétez encore
La réponse de Michael Durrant est à mon humble avis pas mal, mais ce n'est pas littéralement répondre à la question (comme il l'a admis par lui-même), donc je vais essayer de donner une réponse qui fait:
Je comprends également que les commentaires devraient expliquer pourquoi le code fait ce qu'il fait, pas comment.
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée?
Évidemment, vous pouvez écrire un liste de contrôle pour vos revues de code, contenant des questions comme
- "s'il y a un commentaire, cela explique-t-il pourquoi le code fait ce qu'il fait?"
- "Chaque ligne du code - dans son contexte - est-elle suffisamment explicite pour ne pas nécessiter de commentaire, ou sinon, est-elle accompagnée d'un commentaire qui comble cet écart? Ou (de préférence) le code peut-il être modifié de manière à il n'a plus besoin de commentaire? "
Si vous le souhaitez, vous pouvez appeler cela une "norme de codage" (ou non, si vous pensez que le terme norme de codage devrait être réservé à une liste de règles braindead, facile à répondre si elles sont remplies ou non, comment le formatage du code devrait ressembler, ou où déclarer des variables). Personne ne vous empêche d'avoir le focus de votre liste de contrôle sur les questions sémantiques , au lieu de suivre la voie facile et de ne mettre que des règles formelles .
À la fin de la journée, vous devez être sûr que votre équipe a besoin d'une telle liste de contrôle. Pour appliquer ces questions, vous avez besoin de programmeurs ayant une certaine expérience en tant que réviseurs, et vous devez savoir si cela améliorera vraiment la lisibilité du code dans une équipe d'experts. Mais c'est quelque chose que vous devez travailler avec votre équipe.
Anti-pattern majeur conduisant à un code de mauvaise qualité avec moins de clarté
btw lecteurs, le titre était à l'origine "commenter chaque ligne de code?" et vous pouvez imaginer la réaction instinctive de beaucoup d'entre nous, moi y compris. J'ai par la suite retitré le titre plus long et plus précis.
Au début, en lisant votre question, je pensais, dupliquez des trucs dans les commentaires, mais d'accord, peut-être si vous avez suffisamment de restrictions sur les avis de plusieurs personnes ... mais encore une fois: les gens font des erreurs, ne remarquent pas les incohérences, etc. et au fil du temps il y aura finalement des différences. À la réflexion, je pense que le problème est beaucoup plus important:
Les développeurs auront tendance à écrire du code pire. Ils utiliseront plus de noms et de structures cryptiques parce que 'c'est expliqué dans le commentaire - voir!'.
Considérer:
living_room_set = tables + chairs.
Considérez maintenant:
set = tbls+chrs # Make the set equal to the table plus the chairs
Vous avez non seulement à la fois plus de noms cryptiques et plus à lire, vous devez également regarder dans les deux sens, regarder le code, qu'est-ce qu'un ensemble? regardez à gauche le code, regardez à droite les commentaires, quels sont les tbls, regardez à gauche le code, regardez à droite les commentaires, quels sont les chrs, regardez à droite les commentaires. Ouais!
Sommaire
Développez ou améliorez une norme de commentaire si vous êtes obligé de conserver votre position actuelle en tant que développeur (en tant qu'ancienne programmation COBOL, j'en ai certainement vu de grandes!) Mais que vous avez passé autant de temps, d'énergie et de passion à vous opposer aux commentaires anti- modèle utilisant les arguments:
Le code et les commentaires sont désynchronisés lorsqu'ils ne changent qu'un seul
Les commentaires peuvent décrire ce qu'une personne pense, mais ils peuvent se tromper et ainsi masquer les bogues
Le code devient plus difficile à lire
Un bon code devient plus difficile à écrire
Tendance à utiliser plus de noms cryptés
Caractères excessifs à lire dans le code et les commentaires
Différents éditeurs utilisent des styles différents
Nécessite une maîtrise de l'anglais plus élevée que le simple codage
Prend du temps et des ressources et soustrait de la valeur à long terme *
De plus, plaidez pour un meilleur code sans ces commentaires, - en fait, avez un standard (!) - tous les noms de variables doivent être full_english_words - il y en a un! Utilisez donc cette énergie de "normes" vers les normes de code et de tests bien écrits.
L'un des deux problèmes difficiles est de nommer les choses - ne sautez pas le problème avec les commentaires.
Étant donné que l'un des autres problèmes est l'optimisation prématurée et que l'optimisation en général peut conduire à obscurcir le code `` pourquoi de cette façon '', c'est un domaine où des commentaires explicatifs pour un code apparemment médiocre peuvent être bénéfiques bien que les mises en garde ci-dessus s'appliquent toujours.
* code de demain
Je ne pense pas qu'un document sur les normes de codage soit le lieu pour spécifier ce qui est déjà du bon sens. Le but d'une norme de codage est de garantir la cohérence (et d'éviter les arguments) sur des questions où des personnes raisonnables pourraient être en désaccord et il n'y a pas de bonne réponse évidente, par exemple conventions de dénomination, indentation, etc.
Des commentaires comme dans votre exemple sont objectivement inutiles et peuvent être dus à un développeur inexpérimenté ou à un développeur habitué à travailler avec un système de construction qui vérifie mécaniquement la présence de commentaires (une très mauvaise idée, mais elle existe). Dans les deux cas, la solution est l'éducation, éventuellement par le biais de révisions de code.
Si vous commencez à ajouter toutes sortes de "meilleures pratiques" à la norme de codage, vous finirez par répéter ce qui est déjà indiqué dans plusieurs livres. Il suffit d'acheter "Clean Code", "Code Complete" et "The Pragmatic Programmer" au développeur en question, et de garder votre standard de codage maigre.
Ce n'est pas possible. Ce que vous essayez essentiellement de faire, c'est presque de mécaniser le bon jugement.
Lors de l'écriture de logiciels critiques tels que pour les systèmes médicaux de survie, d'énormes quantités de listes de contrôle et ainsi de suite sont pratiquement inévitables. Non seulement les gens intelligents font des erreurs, mais une grande partie du logiciel de ces appareils est écrit par des gens qui ne sont pas très bons dans leur travail, de sorte que le `` système '' doit pouvoir se protéger contre le travail bâclé, le rendant sûr les frais de commercialisation.
Votre meilleure option est de laisser de côté la norme de codage rigoureuse pour commenter et de diriger l'équipe par l'exemple. Montrez aux autres à quoi ressemblent les bons commentaires en s'efforçant de produire un code de bonne qualité qui est correctement commenté. Au lieu d'essayer de trouver la façon ultime de décrire comment écrire des commentaires (qui sont eux-mêmes le plus souvent un jugement), montrez aux autres ce que vous voulez dire quotidiennement avec vos propres révisions de code. Lorsque les autres membres liront votre code, ils emboîteront le pas s'ils le jugent utile. Et s'ils ne le peuvent pas, aucune norme ne les aiderait à rédiger de meilleurs commentaires pour commencer.
Mise à jour
Ma réponse entre guillemets pour souligner:
Je pense que la réponse qui stipule que les commentaires ne doivent pas être traités dans les normes de codage, puis énumère un ensemble de questions défensives pour le combattre, est la seule bonne réponse.
Le problème ici est qu'un Coding Standard est juste cela, un Standard. Les idées extrêmement subjectives devraient pas être dans un Coding Standard. Il peut s'agir d'un guide des meilleures pratiques, mais ce guide ne peut pas être utilisé contre un développeur pendant la révision de code. À mon avis, une norme de codage devrait être aussi proche que possible de l'automatisation. Il y a tellement de temps perdu dans les revues de code qui se disputent sur la dénomination, l'espacement, les tabulations, les crochets, les commentaires, etc., etc. quand tout cela peut être automatisé. Même la réponse concernant
tablesetchairspeut être automatisée. Les LINT'ers permettent des dictionnaires, des vérifications de capitalisation par concept (variable, fonction, méthode, classe, etc.).Même la vérification JavaDoc peut être implémentée par un Robot LINT'er avant qu'une demande de pull soit acceptée. De nombreux projets Open Source font exactement cela. Vous soumettez votre demande Pull, le code est construit avec un fichier Travis-CI, y compris l'analyse statique, et il doit passer toutes les normes de codage qui peuvent être exprimées objectivement. Pas de carillons humains sur le fait de "mal faire" ou de ne pas "fournir de la valeur" avec un commentaire, ou la mauvaise façon de nommer les variables, et al. Ces discussions n'ont aucune valeur et il vaut mieux les laisser à un robot tiers qui peut supporter le poids de notre codage émotionnel.
Pour répondre réellement à la question, nous devons déterminer comment écrire un Standard qui traite de la façon de répondre à la question suivante: Ce commentaire a-t-il fourni une valeur? Une norme de codage ne peut pas éventuellement dicter la "valeur" d'un commentaire. Pour cela, il devient nécessaire pour un humain de passer par cette liste de contrôle. La simple mention de commentaires dans une norme de codage crée une liste de contrôle que l'affiche originale veut éviter.
C'est pourquoi les commentaires ne sont généralement pas traités par le compilateur et supprimés. Leur valeur ne peut être déterminée. Le commentaire en question est-il valable; Oui ou non?. Répondre à cette question est NP-difficile. Seuls les humains ont une chance d'y répondre correctement, et même alors, il ne peut être répondu au moment où il est lu, par la personne qui le lit; où la valeur de ce commentaire est affectée par la météo, sa vie de famille, la dernière réunion à laquelle ils viennent d'assister et qui ne s'est pas bien terminée, l'heure de la journée, la quantité de café qu'ils ont bu. J'espère que l'image devient plus claire.
Comment peut-il jamais être exprimé correctement dans une norme? Une norme n'est utile que si elle peut être appliquée de manière cohérente et équitable, alors que l'équité concerne davantage l'objectivité que l'émotion.
Je conteste qu'une norme de codage doit rester aussi objective que possible. La façon dont les variables sont nommées IS objectif. Elles peuvent facilement être vérifiées par rapport à un dictionnaire pour l'orthographe, la structure grammaticale et la casse appropriées. avec le plus de pouvoir ou en "battant les sourcils". Quelque chose que, personnellement, j'ai du mal à NE PAS faire.
Quand je commente, je commente toujours parler à mon futur moi à la troisième personne. Si je reviens à ce code dans 5 ans, que devrais-je savoir? Qu'est-ce qui serait utile, ce qui serait déroutant et ce qui serait obsolète avec le code? Il existe une différence entre documenter du code pour générer une API publique consultable et commenter du code qui fournit de la valeur à un tiers inconnu, même si ce tiers est vous-même.
Voici un bon test décisif. Si vous étiez le SEUL sur le projet. Vous saviez que vous seriez le seul sur le projet. Quelle serait votre norme de codage? Vous souhaitez que votre code soit propre, explicite et compréhensible pour vous à l'avenir. Auriez-vous un examen du code avec vous-même pour savoir pourquoi vous n'avez pas mis de commentaire sur chaque ligne? Souhaitez-vous revoir chaque commentaire que vous avez créé sur les 100 fichiers que vous avez archivés? Sinon, alors pourquoi forcer les autres?
Je crois que quelque chose manque à ces discussions, c'est que Future You est également développeur de ce projet. Lorsque vous posez des questions sur la valeur, demain, vous êtes également une personne qui peut tirer de la valeur du commentaire. Donc, la taille de l'équipe, à mon avis, n'a pas d'importance. L'expérience d'équipe n'a pas d'importance, elle change trop souvent.
Aucune quantité de code de commentaire examinant cela n'empêche un rythme maker de s'écraser et de tuer un patient. Une fois que vous parlez d'un commentaire qui affecte le code, vous parlez maintenant du code et non du commentaire. S'il suffit d'un commentaire manquant pour tuer quelqu'un, il y a autre chose qui sent dans le processus.
La solution à ce type de codage rigoureux a déjà été apportée comme méthodologie d'écriture du logiciel lui-même. Et cela n'a rien à voir avec les commentaires. Le problème avec les commentaires est qu'ils n'ont AUCUN impact sur le fonctionnement final du produit. Les meilleurs commentaires du monde ne peuvent pas empêcher les logiciels de planter lorsqu'ils sont intégrés dans un générateur de rythme. Ou lors de la mesure des signaux électriques avec un électrocardiogramme portable.
Nous avons deux types de commentaires:
Commentaires lisibles par machine
Les styles de commentaire tels que Javadoc, JSDoc, Doxygen, etc. sont tous des moyens de commenter l'interface publique fournie par un ensemble de codes. Cette interface ne peut être utilisée que par un seul autre développeur (code propriétaire pour une équipe de deux personnes), un nombre inconnu de développeurs (par exemple JMS) ou pour un service entier. Ce code peut être lu par un processus automatisé qui produit alors une manière différente de lire ces commentaires, ala HTML, PDF, etc.
Ce type de commentaire est facile à créer une norme pour. Cela devient un processus objectif pour s'assurer que chaque méthode, fonction, classe invocable publiquement contient les commentaires requis. En-têtes, paramètres, description et. el. Il s'agit de s'assurer qu'il est facile pour une autre équipe de trouver et d'utiliser le code.
Je fais quelque chose qui a l'air fou, mais ce n'est vraiment pas
Ces commentaires sont là pour aider les autres à voir POURQUOI ce code a été écrit d'une certaine manière. Il y a peut-être une erreur numérique dans les processeurs sur lesquels le code s'exécute et il arrondit toujours, mais les développeurs traitent généralement le code qui arrondit. Donc, nous commentons pour nous assurer qu'un développeur qui touche le code comprend pourquoi le contexte actuel fait quelque chose qui semble normalement déraisonnable, mais en réalité a été écrit de cette façon exprès.
Ce type de code est à l'origine de nombreux problèmes. Il n'est généralement pas commenté et est ensuite trouvé par un nouveau développeur et "corrigé". Brisant ainsi tout. Même alors, les commentaires ne sont là que pour expliquer le POURQUOI pour ne pas empêcher quoi que ce soit de se casser.
On ne peut pas se fier aux commentaires
Les commentaires sont finalement inutiles et ne peuvent pas faire confiance. Les commentaires ne modifient normalement pas la façon dont les programmes s'exécutent. Et s'ils le font, votre processus pose plus de problèmes qu'il ne devrait. Les commentaires sont des réflexions après coup et ne peuvent jamais être autre chose que. Le code est tout ce qui compte car c'est tout ce qui est traité par l'ordinateur.
Cela peut sembler insensé, mais supportez-moi. Laquelle de ces deux lignes compte vraiment?
// We don't divide by 0 in order to stop crashes.
return 1 / n;
Dans cet exemple, tout ce qui compte, c'est que nous n'avons aucune idée de ce que 'n' est, il n'y a aucune vérification pour que n soit 0 ET même s'il y en avait, rien n'empêche un développeur de mettre n = 0 APRÈS la vérification de 0. Ainsi, le commentaire est inutile et rien d'automatisé ne peut jamais attraper cela. Aucune norme ne peut attraper cela. Le commentaire, bien que joli (pour certains), n'a aucune incidence sur le résultat du produit.
Développement piloté par les tests
Qu'est-ce qui a un résultat sur le produit? Les industries dans lesquelles le code en cours d'écriture peut littéralement sauver ou tuer quelqu'un doivent être rigoureusement vérifiées. Cela se fait par le biais de revues de code, de revues de code, de tests, de tests, de revues de code, de tests unitaires, de tests d'intégration, d'essais, de staging, de mois de tests, de revues de code et d'essais individuels, de staging, de revues de code, de tests, puis peut-être finalement entrer en production. Les commentaires n'ont rien à voir avec tout cela.
Je préfère un code sans commentaires, avec des spécifications, des tests unitaires qui vérifient les spécifications, des études des résultats de l'exécution du code sur l'appareil de production, puis un code bien documenté qui n'a jamais été testé, et qui n'a rien à comparer code contre.
La documentation est agréable quand vous essayez de comprendre POURQUOI quelqu'un a fait quelque chose d'une certaine manière, cependant, j'ai trouvé au fil des ans que la documentation est généralement utilisée pour expliquer pourquoi quelque chose de "intelligent" a été fait, alors qu'il n'en avait vraiment pas besoin être écrit de cette façon.
Conclusion
Si vous travaillez dans une entreprise qui EXIGE que chaque ligne soit commentée, JE GARANTIT qu'au moins deux des ingénieurs logiciels du projet ont déjà écrit un programme d'auto-documentation en Perl, LISP ou Python qui détermine l'idée générale de ce que fait la ligne, puis ajoute un commentaire au-dessus de cette ligne. Parce que cela est possible, cela signifie que les commentaires sont inutiles. Trouvez les ingénieurs qui ont écrit ces scripts pour documenter automatiquement le code et les utiliser comme preuves pourquoi le "Commentaire sur chaque ligne" fait perdre du temps, n'apporte aucune valeur et peut potentiellement nuire.
En passant, j'aidais un ami proche avec une affectation de programmation. Son professeur avait exigé que chaque ligne soit documentée. Je peux donc voir d'où proviendrait ce processus de réflexion. Demandez-vous simplement ce que vous essayez de faire et est-ce la bonne chose? Alors demandez-vous; Existe-t-il un moyen de "jouer" le système avec ce processus? Si tel est le cas, ajoute-t-il vraiment de la valeur? On ne peut pas écrire automatiquement des tests unitaires qui testent que le code répond à une certaine spécification, et s'ils le pouvaient, ce ne serait pas une mauvaise chose.
Si un appareil doit fonctionner dans certaines conditions parce qu'il sera à l'intérieur d'un être humain, la seule façon de s'assurer qu'il ne va pas les tuer est des années de tests, d'examen par les pairs, d'essais, puis de ne JAMAIS JAMAIS changer le code à nouveau. C'est la raison pour laquelle la NASA utilise/utilisait encore de vieux matériels et logiciels. Quand il s'agit de la vie ou de la mort, vous ne vous contentez pas de `` faire un petit changement et de vérifier.
Les commentaires n'ont rien à voir avec le sauvetage de vies. Les commentaires sont pour les humains, les humains font des erreurs, même lorsqu'ils écrivent des commentaires. Ne faites pas confiance aux humains. Ergo, ne fais pas confiance aux commentaires. Les commentaires ne sont pas votre solution.
Il y a deux choses différentes auxquelles vous faites allusion lorsque vous parlez de commentaires. Ce ne sont pas les mêmes, et la distinction est importante.
Documentation vous informe sur les bits orientés vers l'extérieur d'un morceau de code - son interface.
Les outils vous permettent généralement de les lire de manière `` autonome '', c'est-à-dire que vous ne regardez pas le code sous-jacent en même temps.
Toute l'interface doit être documentée (par exemple, chaque méthode, à l'exclusion des méthodes privées), et elle doit décrire les entrées, les sorties et toutes autres attentes, limitations, etc., en particulier les choses qui ne peuvent pas être exprimées par des contraintes, des tests, etc. ( La quantité exacte de détails et leur destination dépendent du projet).
Une bonne documentation permet au consommateur potentiel de décider si, quand et comment utiliser le code.
Commentaires dans le code source ont un but différent. Ils sont là pour les personnes qui consultent le code source. Ils décrivent principalement la mise en œuvre.
Les commentaires sont toujours lus dans le code sous-jacent.
Les commentaires doivent expliquer des décisions surprenantes ou des algorithmes complexes, ou des options non prises (et raisonnement). Ils sont là pour que les futurs développeurs puissent comprendre les processus de réflexion de leurs prédécesseurs et avoir à portée de main des informations qu'ils pourraient autrement ignorer ou passer beaucoup de temps à rechercher, par exemple.
# 'map' outperforms 'for' here by a factor of 10
// This line works around an obscure bug in IE10, see issue #12053
-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.
Vous ne pouvez rien déduire de l'absence de commentaire, et le commentaire peut bien sûr être aussi faux que le code environnant ou plus encore. Le jugement doit être exercé à la fois par l'auteur et par le lecteur.
Commenter chaque ligne est clairement plus de travail d'une valeur supplémentaire discutable, qui s'accompagne d'un coût d'opportunité. Si vous avez une règle qui dit que chaque ligne doit être commentée, vous l'obtiendrez, mais au détriment des parties importantes commentées bien .
Mais c'est pire que cela: le but d'un commentaire est vaincu si chaque ligne est commentée. Les commentaires deviennent du bruit qui rend le code difficile à lire: obscurcissant plutôt que clarifiant. De plus, les commentaires aveugles rendent les commentaires vraiment importants plus difficiles à repérer.
Ni les commentaires ni la documentation ne fournissent une quelconque mesure ou garantie de la qualité du code qu'ils décrivent; ils ne remplacent pas un véritable AQ. Leur objectif est tourné vers l'avenir, c'est-à-dire dans l'espoir qu'ils aideront ceux qui interagissent avec celui-ci à éviter de faire des erreurs.
En résumé, vos normes de codage peuvent et doivent exiger de la documentation (les vérifications automatisées aident à repérer les fonctions/méthodes non documentées, mais les humains doivent toujours vérifier si la documentation est bonne). Les commentaires sont un jugement, et votre guide de style devrait le reconnaître. Ceux qui ne commentent jamais et ceux qui commentent sans réfléchir devraient s'attendre à être mis au défi.
Vous ne pouvez pas codifier une norme de commentaire, car vous ne pouvez pas savoir à l'avance quel sera le commentaire important.
Mais vous voulez toujours vous assurer que le code est correctement commenté, car il s'agit d'un code vital. La solution est d'avoir un standard pour la révision du code - exiger que la révision du code commente la compréhensibilité.
Cela ne garantit pas qu'il ne se transformera pas en une liste de contrôle vide de sens, mais cela l'empêchera au moins de rendre le code plus difficile à lire. Et a la possibilité de l'améliorer.
Cela nécessite une culture où la révision du code n'est pas en soi un geste dénué de sens, où le fait de renvoyer votre code aussi difficile à lire est une bonne chose, et non une insulte ou une gêne. Tout aussi important, celui où il n'était pas clair, n'est pas considéré comme un échec du lecteur.
Le code illisible est, dans une certaine mesure, inévitable. Parce que l'écrivain est immergé dans le contexte et verra quelque chose comme évident quand ce n'est évident que si vous connaissez x, y ou z.
Donc, vous ne pourrez pas avoir une règle qui dit donner de bons commentaires, mais vous pouvez vérifier les avis. Même un gestionnaire non programmeur pourrait le faire - car la vraie question n'est pas le code écrit pour être lisible, mais le code en fait lisible, qui ne peut être décidé que par quelqu'un qui l'a lu .
Commenter chaque ligne de code? Non.
Le but des autres règles dont vous parlez est précisément d'éviter cela.
Les commentaires sur un code lisible sont au mieux redondants et, au pire, découragent le lecteur de chercher le but inexistant du commentaire.
Si vous commentez un code entier qui s'explique de lui-même, vous doublez la quantité de lecture sans donner d'informations supplémentaires. Je ne sais pas si une telle redondance serait payante. On peut imaginer un critique disant que 42 dit "display_error "tandis que le commentaire dit" affiche un avertissement ". Mais imaginez un changement dans le code. Vous avez maintenant deux points à corriger. Il devient clair que ce style a des négatifs copier-coller.
Je dirais que de manière optimale, le code ne devrait pas avoir besoin de commentaires, autres que la documentation.
Il y a des styles qui vont totalement à l'opposé, si vous avez des doutes sur la ligne c'est soit:
Le code est trop compliqué et devrait être refactorisé en une fonction avec un nom avec une signification sémantique pour la partie de code. Que ce soit un
ifcomplexe ou une partie d'un algorithme. (Ou une doublure intelligente LINQ)Si cela ne peut pas être simplifié, vous ne connaissez pas suffisamment les idiomes du langage.
(Personnellement, je ne suis pas un fanatique de la règle stricte de non-commentaires, mais je trouve que c'est un bon état d'esprit initial.)
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée?
Quant au processus. Notre norme a donné beaucoup de crédit à la critique. En supposant qu'ils ne sont pas malveillants, cela fonctionne bien.
Lorsqu'il demande "Qu'est-ce que la variable o?", Vous la renommez. S'il demande ce que fait ce bloc, refactorisez ou commentez. S'il y a eu un débat pour savoir si quelque chose est clair ou non, si l'examinateur ne l'a pas compris, alors, par définition, ce n'est pas le cas. En de très rares occasions, il y avait quelque chose comme la 2e opinion de quelques amis.
En moyenne, vous devriez obtenir un code compréhensible par le programmeur moyen de l'équipe. OMI, il conserve les informations redondantes et garantit que le code est compréhensible par au moins un autre membre de l'équipe, ce que nous avons trouvé un bon optimum.
Aussi, il n'y avait pas d'absol. Même si nous étions un petit groupe. Il est facile de trouver un consensus en groupe de 5.
La question:
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée? Ceux qui seront pertinents dans un examen par les pairs mais ne se transformeront pas en une activité de liste de contrôle stupide qui ne produira pas de notes plus utiles que: "Vous avez oublié de commenter à la ligne 42".
Les commentaires ne doivent pas chercher à éduquer le lecteur sur la langue. Un lecteur devrait être supposé connaître la langue mieux que l'écrivain, mais avec beaucoup moins de contexte que l'écrivain.
Un lecteur de ce code, à partir de votre exemple, devrait savoir que exit() quittera l'application - rendant ainsi le commentaire redondant:
/* Exit the application */
exit();
Les commentaires redondants sont une violation de DRY, et les modifications du code ne se propagent pas nécessairement aux commentaires, laissant des commentaires qui ne reflètent pas ce que le code est réellement Faire.
Cependant, les commentaires qui expliquent pourquoi vous faites quelque chose peuvent être utiles - surtout si vous ne pouvez pas facilement communiquer la signification dans le code lui-même.
Python's PEP 8 (le guide de style pour Python dans la bibliothèque standard de CPython) fournit la directive suivante pour les commentaires en ligne:
Utilisez les commentaires en ligne avec parcimonie.
Un commentaire en ligne est un commentaire sur la même ligne qu'une instruction. Les commentaires en ligne doivent être séparés d'au moins deux espaces de l'instruction. Ils doivent commencer par un # et un seul espace.
Les commentaires en ligne sont inutiles et en fait distrayants s'ils indiquent l'évidence. Ne faites pas ça:
x = x + 1 # Increment xMais parfois, cela est utile:
x = x + 1 # Compensate for border
Étant donné un tel exemple, je préfère personnellement aller plus loin et j'essaierais également d'éliminer ce commentaire. Par exemple, je pourrais arriver à:
border_compensation = 1
compensated_x = x + border_compensation
Faire votre code l'auto-documentation n'est pas une nouvelle idée .
Retour à la question réelle:
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée?
Je crois que les conseils et l'exemple de PEP 8 démontrent une bonne norme de codage qui capture cette idée. Alors oui, je pense que c'est possible.
Je pense que lorsque vous voyez ce genre de commentaire, et j'écris moi-même de cette façon de temps en temps, c'est parce que l'auteur écrit la spécification dans les commentaires, puis passe en revue et met en œuvre chaque commentaire.
Si nous sommes mis au défi d'écrire une norme de codage qui produit un code compréhensible en termes de fonctionnalités requises plutôt que de fonctionnalités réelles (afin que les erreurs puissent être repérées), parlons-nous vraiment de la façon dont les spécifications sont définies, documentées et liées à le produit final?
éditer ----
Juste pour clarifier. Je n'entre pas dans les commentaires vs tdd vs tests unitaires qui le mieux. Ou suggérer un commentaire par ligne est un bon/mauvais
Je suggère simplement une raison pour laquelle vous pourriez voir le style de commentaire mentionné dans l'exemple.
Et à partir de cette question de savoir si une norme de codage sur les commentaires serait vraiment mieux écrite comme une exigence de document de spécification d'une certaine sorte.
c'est-à-dire que les commentaires servent à expliquer le but du code, qui est aussi ce qu'est une spécification
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée? Ceux qui seront pertinents dans un examen par les pairs mais ne se transformeront pas en une activité de liste de contrôle stupide qui ne produira pas de notes plus utiles que: "Vous avez oublié de commenter à la ligne 42".
Cela va bien au-delà de la documentation - cela concerne la façon dont le code est structuré, les algorithmes choisis, etc. Cela peut même toucher à l'analyse et à la conception des exigences.
Ma règle n ° 1 est "Ne documentez pas l'évidence". La règle n ° 2 est "Écrire un code évident".
Pour le code critique pour la sécurité (sur lequel je n'ai jamais eu à travailler, Dieu merci), c'est une première étape nécessaire mais loin d'être suffisante. Cela peut même devoir se résumer à imposer les fonctionnalités du langage à éviter (j'ai vu plus d'une norme imposant "Tu n'utiliseras pas scanf( "%s", input );pour une raison quelconque").
À mon humble avis, il devrait faire les deux. Commenter chaque ligne est idiot, car vous vous retrouvez avec des lignes comme
i++; /* Increment i */
avec absolument aucune idée de pourquoi vous voudriez incrémenter i. Développez-le un peu, et vous avez le style typique de commentaires Doxygen, qui produit une grande quantité de verbiage sans fournir aucune idée de ce à quoi le code est destiné, ou comment il fonctionne. (Au moins pour autant que je l'ai jamais vu: j'admets qu'il pourrait être possible d'écrire une documentation utile en utilisant un système comme celui-ci, mais je ne retiens pas mon souffle.)
OTOH, si vous écrivez un bon bloc de commentaires en tête de la fonction (ou quel que soit le regroupement logique), décrivant à la fois ce qui doit être accompli et comment, si ce n'est pas évident, vous avez quelque chose d'utile. Si vous êtes moi, vous pouvez même inclure du code LaTeX pour les équations pertinentes ou des références à des articles, par exemple "Ceci implémente un schéma WENO pour résoudre les équations de Hamilton-Jacobi, comme discuté dans ..."
La meilleure pratique du code auto-documenté n'est pas un consensus général - bien qu'il soit largement acceptable qu'un code facile à comprendre soit meilleur qu'un code cryptique, tout le monde n'est pas d'accord sur le fait de savoir si le code compliqué doit toujours être refactorisé ou s'il est acceptable de commenter il.
Mais ce débat porte sur morceaux de code qui sont difficiles à comprendre - et vous parlez de commenter chacun ligne de code. Les lignes de code difficiles à comprendre devraient être très rares - si la plupart de vos lignes sont compliquées comme celle-ci, vous utilisez trop les lignes simples intelligentes et vous devez vous arrêter! Bien sûr, le rôle d'une ligne peut être un peu difficile à comprendre parfois, mais c'est son rôle dans le contexte d'un plus gros morceau de code - ce que fait la ligne elle-même est presque toujours simple.
Donc, vous ne devez pas commenter des lignes - vous devez commenter des morceaux de code. Des commentaires spécifiques peuvent être placés près des lignes auxquelles ils se réfèrent, mais ces commentaires se réfèrent toujours au code plus gros. Ils ne décrivent pas ce que/pourquoi la ligne fait - ils décrivent ce qu'elle fait dans ce code et/ou pourquoi est-elle nécessaire dans ce code.
Ce ne sont donc pas les lignes qui doivent être commentées mais les morceaux de code plus gros. Faut-il commenter chaque morceau de code? Non. Harold Abelson a dit que " Les programmes doivent être écrits pour que les gens puissent les lire, et accessoirement pour que les machines s'exécutent". Mais les commentaires sont seulement pour que les gens les lisent - la machine ne les exécute pas. Si vos normes de codage forcent l'écriture de commentaires redondants sur chaque ligne/morceau de code, vous n'imposez pas seulement le développeur qui doit les écrire - vous surchargez également les développeurs qui devront lire eux!
C'est un problème, parce que lorsque la plupart des commentaires que vous lisez sont redondants, vous cessez de faire attention à eux (parce que vous savez qu'ils ne seront que des ordures redondantes), et ensuite vous manquerez l'important = commentaires. Je dis donc - n'écrivez que le commentaire important, de sorte que lorsque quelqu'un verra un commentaire dans le code, il saura qu'il vaut la peine de le lire afin de comprendre le code.
Il est temps de ramener les organigrammes! (pas vraiment mais attendez une minute)
L'autre jour, j'ai trouvé mon ancien modèle d'organigramme. Je ne l'ai utilisé que pour les devoirs et les blagues (tu dois aimer un bon organigramme idiot). Mais même à cette époque, la plupart des programmeurs commerciaux qui utilisaient encore des organigrammes les généraient automatiquement à partir du code (ce qui sape complètement l'objectif initial de l'organigramme, qui devait aider à écrire un meilleur code et était très utile dans le code machine. Cependant, avec les langages de niveau supérieur, l'organigramme est passé d'une béquille à un hoble. Pourquoi? L'abstraction de l'organigramme était la même que le code. Les commentaires affichés sont une entrave car ils sont au même niveau d'abstraction que le code. Les bons commentaires sont à un niveau d'abstraction différent de celui du code. La façon la plus simple de le faire est d'utiliser les commentaires pour savoir pourquoi tandis que le code gère quoi. Les autres méthodes consistent à décomposer les étapes compliquées en remplaçants plus simples ou à avoir des résumés de niveau gestionnaire.
Je répondrai à la question comme indiqué:
Étant donné tout cela, est-il même possible d'écrire de bonnes normes de codage qui captent cette idée?
Oui. WYSIWYG. Un bon standard de codage est littéralement "est clair pour le lecteur ce que fait le code suivant et pourquoi ".
En d'autres termes, mes commentaires de révision de code sur la lisibilité du code littéralement, 1-1, découlent de mon état mental de
En tant que lecteur, (mieux encore, en tant que norme minimale, un modèle mental de lecteur moins expérimenté mais raisonnable), je ne comprendrais pas le but ou la méthode de travail du code suivant
Généralement, les gens sont faciles à embarquer "cela a besoin de plus de lisibilité" lorsqu'ils entendent "Moi, en tant que développeur senior que vous respectez, je l'espère, comme n'étant pas stupide, je n'ai pas d'abord lu comprendre ce code ou pourquoi il est là ou ce qu'il le fait, il doit donc être expliqué ".
Cela fait passer le discours de "vous n'avez pas suivi une norme dénuée de sens" à "votre code présente un défaut de lisibilité spécifique conduisant à un problème pratique".
Un deuxième standard qui doit être explicité est le "test d'urgence à 2h du matin".
Votre sauvegarde, qui ne connaît pas ce code, peut-elle comprendre quel est le problème avec le code lors du débogage lors d'un appel d'urgence de production à 2 heures du matin, lorsque vous êtes en vacances dans les Andes chiliennes sans téléphone portable?
Cela peut sembler subjectif, mais il est en fait facile à mesurer pratiquement: appelez un membre de l'équipe junior au hasard qui devrait être le seul à déboguer la nuit en cas d'urgence de production, et demandez-leur d'expliquer comment fonctionne le code non commenté particulier et pourquoi il est Là.
Cette réponse a couvert la plupart des problèmes, mais il y a une chose importante.
Je voudrais capturer une idée dans le sens de: considérer un commentaire pour chaque ligne, séquence, instruction, section, structure, fonction, méthode, classe, package, composant, ... de code.
Il existe des outils pour générer de la documentation à partir de code, comme par exemple doxygen. Si vous utilisez de tels outils, il est logique de commenter des fichiers, des fonctions, des classes, etc. Même si le nom de la fonction est explicite, je le fais toujours par souci de cohérence, car les personnes qui liront la documentation seront reconnaissantes.