Norme de codage pour plus de clarté: commentez-vous chaque ligne de code?

J'ai travaillé dans des ateliers qui produisent des logiciels essentiels à la vie courante et j'ai traité des règles de commentaire destinées à garder le code lisible et potentiellement à sauver des vies. D'après mon expérience, l'exigence devient une corvée de cerveau fatal d'être cochée dans une liste de contrôle et ne m'aide pas à rester concentrée sur l'écriture de code compréhensible. Cela empêche également mon relecteur d'avoir une conversation plus significative avec moi sur la manière de rendre le code plus facile à comprendre.

J'ai aussi noté le code des étudiants sans commentaire et vu pourquoi ils devraient être marqués pour les avoir négligés.

Je comprends que l’utilisation de bons noms, la simplicité des structures, la brièveté des fonctions et la focalisation des modules permettent au code d’être suffisamment compréhensible pour que les commentaires puissent être minimisés.

Je comprends aussi que les commentaires devraient expliquer pourquoi le code fait ce qu’il fait, pas comment.

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée? Celles qui seront pertinentes dans une évaluation par les pairs mais ne se transformeront pas en une activité insensée dans la liste de contrôle produisant des notes tout aussi utiles que: "Vous avez oublié de commenter la ligne 42".

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 d'exprimer cela correctement dans un document de normalisation, et que ce n'est peut-être tout simplement pas le cas, j'aimerais capturer une idée dans ce sens:

Considérons un commentaire pour chaque ligne, séquence, instruction, section, structure, fonction, méthode, classe, package, composant, ... du code. Ensuite, envisagez de renommer et de simplifier le nom pour éliminer le besoin de ce commentaire et le supprimer. Check in alors que les commentaires sont rares. Répétez jusqu'à la date limite. Puis répète encore

La réponse de Michael Durrant est IMHO pas mal, mais elle ne répond pas littéralement à la question (comme il l'a admis lui-même), je vais donc essayer de donner une réponse qui:

Je comprends aussi que les commentaires devraient expliquer pourquoi le code fait ce qu’il fait, pas comment.

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée?

Évidemment, vous pouvez écrire une liste de contrôle pour vos critiques de code , contenant des questions telles que

• "s'il y a un commentaire, explique-t-il pourquoi le code fait ce qu'il fait?"
• "chaque ligne du code - dans son contexte - est-elle suffisamment explicite au point de ne pas nécessiter de commentaire, ou est-elle accompagnée d'un commentaire qui comble cette lacune? Ou (de préférence) le code peut-il être modifié 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 doit être réservé à une liste de règles simples, il est facile de répondre si elles sont remplies ou non, comment le formatage du code devrait ressembler, ou où déclarer les variables). Personne ne vous empêche d'avoir le focus de votre liste de contrôle sur des questions sémantiques , au lieu d'aller dans la voie de la facilité et d'y mettre uniquement des règles formelles .

À la fin de la journée, vous devez vous assurer 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. Vous devez également déterminer si cela améliorera réellement la lisibilité du code dans une équipe d'experts. Mais c’est quelque chose que vous devez régler avec votre équipe.

Anti-motif majeur conduisant à un code de mauvaise qualité avec moins de clarté

d'ailleurs, le titre était à l'origine "commenter chaque ligne de code?" et vous pouvez imaginer la réaction instinctive de beaucoup d'entre nous, y compris moi-même. J'ai plus tard renommé le titre plus long et plus précis.

Au début, en lisant votre question, je pensais qu'il y avait des doublons dans les commentaires, mais bon, peut-être que vous avez suffisamment de restrictions sur les avis de plusieurs personnes ... mais encore une fois: les gens font des erreurs, ne remarquent pas d'incohérences, etc. il y aura des différences. À la réflexion, je pense que le problème est beaucoup plus vaste:

Les développeurs auront tendance à écrire du code pire. Ils utiliseront davantage de noms et de structures cryptiques car 'cela est expliqué dans le commentaire - voir!'.

Considérer:

living_room_set = tables + chairs.

Considérons maintenant:

set = tbls+chrs # Make the set equal to the table plus the chairs

Vous avez non seulement plus de noms cryptés et plus à lire, vous devez également regarder en arrière, regarder le code, qu'est-ce qu'un ensemble? regarde à gauche le code, regarde à droite les commentaires, quels sont les tableaux, regarde à gauche le code, regarde à droite les commentaires, quels sont les enfants, regarde à droite le commentaire. Yuch!

Sommaire

Développez ou améliorez une norme de commentaires si vous êtes obligé d’occuper votre poste actuel de développeur (en tant qu’ancien programme COBOL, j’en ai certainement vu de grandes!) Mais que vous avez consacré autant de votre temps, de votre énergie et de votre passion à lutter contre les commentaires antérieurs. motif utilisant les arguments:

• Le code et les commentaires ne sont plus synchronisés les uns avec les autres

• Les commentaires peuvent décrire ce qu'une personne pense mais qui pourrait avoir tort et dissimuler ainsi des bugs

• Le code devient plus difficile à lire

• Bon code devient plus difficile à écrire

• Tendance à utiliser davantage de noms cryptiques

• Caractères excessifs à lire dans le code et les commentaires

• Différents éditeurs utilisent différents styles

• Nécessite une maîtrise de l'anglais supérieure à celle du simple codage

• Prend du temps et des ressources et soustrait de la valeur à long terme *

De plus, nous plaidons pour un meilleur code sans de tels commentaires, - en fait, utilisez un standard (!) - tous les noms de variables doivent être full_english_words - il y en a un! Utilisez donc cette énergie «standard» pour atteindre les standards de code et de tests bien écrits.

Un des deux problèmes difficiles est de nommer des choses - ne sautez pas le problème avec des 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 "de cette façon", il s'agit d'un domaine dans lequel des commentaires explicatifs pour un code apparemment médiocre peuvent être bénéfiques, bien que les mises en garde susmentionnées s'appliquent toujours.

* code de demain

Je ne pense pas qu'un document sur les normes de codage soit l'endroit idéal pour préciser 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 pour lesquelles des personnes raisonnables pourraient ne pas être d'accord et en l'absence de bonne réponse évidente, par exemple les conventions de dénomination, l'indentation, etc.

Les commentaires tels que dans votre exemple sont objectivement inutiles et peuvent être dus à un développeur inexpérimenté, ou un développeur travaillait 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. Achetez simplement "Clean Code", "Code Complete" et "The Pragmatic Programmer" au développeur en question, et maintenez votre code de qualité standard.

Ce n'est pas possible. Ce que vous essayez essentiellement de faire est presque de mécaniser le bon jugement.

Lors de la rédaction de logiciels critiques, tels que les systèmes médicaux indispensables à la vie, d’énormes quantités de listes de contrôle et autres sont pratiquement inévitables. Même les personnes les plus intelligentes commettent des erreurs, de nombreux logiciels de ces appareils ont été conçus par des personnes qui ne sont pas très douées pour leur travail. Le «système» doit donc être en mesure de protéger le travail négligé, en le protégeant sans danger. le coût de la commercialisation.

Votre meilleure option est de laisser de côté la norme de codage rigoureuse pour les commentaires et de diriger l’équipe par l’exemple. Montrer aux autres comment sont les bons commentaires en s'efforçant de produire un code de bonne qualité, commenté de manière appropriée. Au lieu d'essayer de trouver le moyen ultime de décrire comment écrire des commentaires (qui sont le plus souvent un jugement), montrez aux autres ce que vous voulez dire quotidiennement avec vos propres critiques de code. Au fur et à mesure que les autres membres liront votre code, ils feront de même s'ils le jugent utile. Et s’ils ne le peuvent pas, aucune norme ne les aiderait à rédiger de meilleurs commentaires.

Mise à jour

Ma réponse entre guillemets pour souligner:

Je suis convaincu que la réponse qui stipule que les commentaires ne doivent pas être abordés dans les normes de codage, puis énumère un ensemble de questions défensives pour le combattre, est la seule réponse correcte.

Le problème ici est qu’une norme de codage n’est que cela, une norme . Les idées extrêmement subjectives ne devraient pas figurer dans une norme de codage . Il peut s'agir d'un guide des meilleures pratiques, mais ce guide ne peut pas être utilisé contre un développeur lors de la révision du code. À mon avis, une norme de codage devrait être aussi proche que possible de l'automatisé. Il y a tellement de temps perdu dans les revues de code à discuter de la dénomination, de l'espacement, des tabulations, des crochets, des commentaires, etc., alors que TOUT peut être automatisé. Même la réponse à propos de tableset chairspeut être automatisée. Les LINT'ers autorisent les dictionnaires, les contrôles de capitalisation par concept (variable, fonction, méthode, classe, etc.).

Même la vérification JavaDoc peut être mise en œuvre par un robot LINT'er avant qu'une demande d'extraction soit acceptée. Beaucoup de projets Open Source font exactement cela. Vous soumettez votre demande d'extraction, le code est construit avec un fichier Travis-CI, y compris l'analyse statique, et il doit satisfaire à toutes les normes de codage pouvant être exprimées de manière objective. Aucun humain ne sonne à propos de "mal faire" ou de "valeur" avec un commentaire, ou de la mauvaise façon de nommer des variables, et al. Ces discussions ne fournissent aucune valeur et sont mieux laissées à un robot tiers qui peut supporter le poids de notre codage émotionnel.

Pour réellement répondre à la question, il faudrait que nous écrivions une norme qui répondrait à la question suivante: Ce commentaire at-il une valeur? Une norme de codage ne peut pas dicter la "valeur" d'un commentaire. Pour cette raison, il devient nécessaire pour un humain de parcourir 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 souhaite é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 utile? Oui ou non?. Répondre à cette question est NP-difficile. Seuls les humains ont une chance de bien y répondre, et même dans ce cas, la personne qui le lit ne peut y répondre qu'au moment de la lire. où la valeur de ce commentaire dépend de la météo, de la vie de son foyer, de la dernière réunion à laquelle ils viennent d'assister et qui ne s'est pas bien terminée, de l'heure de la journée et de la quantité de café qu'ils ont pris. J'espère que la photo devient plus claire.

Comment peut-il ê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, lorsque juste signifie plus d'objectivité que d'émotionnel.

Je conteste le fait qu'une norme de codage doit rester aussi objective que possible. La façon dont les variables sont nommées objectif IS. Ils peuvent facilement être comparés à un dictionnaire pour l’orthographe, la structure grammaticale et l’habillage appropriés. Tout ce qui est au-delà est un "match de pisse" qui est gagné par la personne qui a le plus de pouvoir ou par "se battre les sourcils". Quelque chose que je lutte personnellement avec 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 pourrait être utile, qu'est-ce qui pourrait prêter à confusion et qu'est-ce qui serait obsolète avec le code? Il existe une différence entre le code de documentation pour générer une API publique interrogeable et le code de commentaire qui fournit une 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. Qu'y aurait-il dans votre norme de codage? Vous voudriez que votre code soit propre, explicite et compréhensible pour vous-même à l'avenir. Souhaitez-vous une révision de code avec vous-même sur les raisons pour lesquelles vous n'avez pas mis de commentaire sur chaque ligne? Souhaitez-vous passer en revue chaque commentaire que vous avez créé sur les 100 fichiers que vous avez archivés? Si non, alors pourquoi forcer les autres?

Je pense que quelque chose manque dans ces discussions, c'est que Future You est également un développeur de ce projet. Quand vous posez des questions sur la valeur, demain, vous êtes également une personne qui peut tirer une 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, cela change trop souvent.

Aucune quantité de code de commentaire passant en revue n'empêche un stimulateur de planter 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. Si tout ce qu'il faut, c'est un commentaire manquant pour tuer quelqu'un, il y a autre chose qui sent le processus.

La solution à ce type de codage rigoureux a déjà été fournie en tant que méthodologie pour écrire un 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 au monde ne peuvent empêcher les logiciels de planter lorsqu'ils sont intégrés à un stimulateur. Ou lors de la mesure des signaux électriques avec un électrocardiographe portable.

Nous avons deux types de commentaires:

Commentaires lisibles par machine

Les styles de commentaire tels que Javadoc, JSDoc, Doxygen, etc. constituent tous des moyens de commenter l'interface publique fournie par un ensemble de code. 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 par un département entier. Ce code peut être lu par un processus automatisé qui produit alors une manière différente de lire ces commentaires, tels que HTML, PDF, etc.

Ce type de commentaire est facile à créer une norme pour. Il devient un processus objectif permettant d’assurer que chaque méthode, fonction ou classe pouvant être appelée publiquement contienne les commentaires requis. En-têtes, paramètres, description et. el. Cela permet à une autre équipe de trouver et d'utiliser facilement le code.

Je fais quelque chose qui semble fou, mais ce n'est vraiment pas

Ces commentaires sont ici pour aider les autres à savoir POURQUOI ce code a été écrit d’une certaine manière. Il existe peut-être une erreur numérique dans les processeurs sur lesquels le code est exécuté et les arrondis sont toujours arrondis, mais les développeurs gèrent généralement le code qui les arrondit. Nous commentons donc pour nous assurer que le développeur qui manipule le code comprend pourquoi le contexte actuel fait quelque chose qui semblerait normalement déraisonnable, mais qui en réalité a été écrit ainsi.

Ce type de code est ce qui cause tant de problèmes. Il va généralement sans commentaires et est ensuite trouvé par un nouveau développeur et "corrigé". Donc tout casser. Même dans ce cas, les commentaires ne sont là que pour expliquer le POURQUOI ne pas empêcher quoi que ce soit de casser.

On ne peut pas compter sur les commentaires

Les commentaires sont finalement inutiles et on ne peut pas leur faire confiance. Les commentaires ne changent normalement pas le mode de fonctionnement des programmes. Et s’ils le font, alors votre processus cause plus de problèmes qu’il devrait le faire. Les commentaires sont des pensées après coup et ne peuvent jamais être autre chose. Le code est tout ce qui compte car c’est tout ce qui est traité par l’ordinateur.

Cela peut sembler bizarre, 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 est que nous ne sachions pas ce que c'est 'n', il n'y a pas de contrôle pour que n soit égal à 0, et même s'il y en avait, rien n'empêche un développeur de mettre n = 0APRÈS le contrôle de 0. Ainsi, le commentaire est inutile et rien automatisé ne peut jamais attraper cela. Aucune norme ne peut attraper cela. Le commentaire, bien que joli (à 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 des révisions de code, des révisions de code, des tests, des révisions, des révisions de code, des tests unitaires, des tests d’intégration, des essais d’intégration, des essais, des tests sur plusieurs mois, des examens de code et des essais pour une seule personne, des évaluations de code, des examens, et enfin peut-être enfin. entrer dans la production. Les commentaires n'ont rien à voir avec cela.

Je préférerais que le code ne contienne AUCUN commentaire, ait une spécification, ait des tests unitaires qui vérifient la spécification, des études des résultats de l'exécution du code sur le périphérique de production, puis un code bien documenté qui n'a jamais été testé, ni rien qui puisse comparer les résultats. code contre.

La documentation est agréable lorsque vous essayez de comprendre POURQUOI quelqu'un a fait quelque chose d'une certaine manière, cependant, j'ai découvert au fil des ans que la documentation est généralement utilisée pour expliquer pourquoi une chose "intelligente" a été faite, alors qu'elle n'en avait vraiment pas besoin être écrit de cette façon.

Conclusion

Si vous travaillez dans une entreprise qui DEMANDE que chaque ligne soit commentée, je vous garantis qu'au moins deux des ingénieurs en logiciels du projet ont déjà écrit un programme auto-documenté en Perl, Lisp ou Python qui détermine l’idée générale de ce que fait la ligne. , ajoute ensuite 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 utilisez-les comme preuve de la raison pour laquelle le "Commentaire sur chaque ligne" fait perdre du temps, ne fournit aucune valeur et peut être préjudiciable.

D'un côté, j'aidais un ami proche avec un travail de programmation. Son professeur avait imposé à chaque ligne d'être documentée. Je peux donc voir d'où viendrait ce processus de pensée. Demandez-vous simplement ce que vous essayez de faire et est-ce la bonne chose à faire? Alors demandez-vous; Existe-t-il un moyen de «jouer» au système avec ce processus? Si c'est le cas, ajoute-t-il vraiment une valeur? On ne peut pas écrire automatiquement des tests unitaires qui vérifient que le code respecte une certaine spécification, et s’ils le pouvaient, ce ne serait pas une mauvaise chose.

Si un périphérique doit fonctionner dans certaines conditions, car il se trouve à l'intérieur d'un humain, le seul moyen de s'assurer qu'il ne va pas le tuer est des années de test, d'examen par les pairs, de tests et de NE JAMAIS JAMAIS changer le code à nouveau. C'est pourquoi la NASA utilise / utilisait encore de tels matériels et logiciels. En ce qui concerne la vie ou la mort, vous ne faites pas simplement un petit changement et vous ne l'enregistrez pas.

Les commentaires n'ont rien à voir avec sauver des 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 faites pas confiance aux commentaires. Les commentaires ne sont pas votre solution.

Vous faites allusion à deux choses différentes lorsque vous parlez de commentaires. Ils ne sont pas les mêmes et la distinction est importante.

La documentation vous informe sur les éléments extérieurs d'un morceau de code, son interface.

Généralement, les outils vous permettent de les lire de manière «autonome», c'est-à-dire que vous ne regardez pas le code sous-jacent en même temps.

Toutes les interfaces doivent être documentées (par exemple, chaque méthode, à l’exception des méthodes privées) et décrire les entrées, les sorties et toute autre attente, limitation, etc., en particulier les éléments qui ne peuvent être exprimés par des contraintes, des tests, etc. ( La quantité 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.

Les 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 un raisonnement). Ils sont là pour que les futurs développeurs puissent comprendre les processus de pensée de leurs prédécesseurs et avoir sous la main des informations qu’ils pourraient sinon oublier ou passer beaucoup de temps à chercher, 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 d'un commentaire, et le commentaire peut bien sûr être aussi faux que le code qui l'entoure ou plus encore. Le jugement doit être exercé à la fois par l'auteur et par le lecteur.

Le fait de commenter chaque ligne est clairement un travail d’une valeur supplémentaire discutable, qui a 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 bien commentées .

Mais c'est pire que cela: le but d'un commentaire est annulé si chaque ligne est commentée. Les commentaires deviennent des bruits qui rendent le code difficile à lire: obscurcir plutôt que clarifier. De plus, les commentaires aveugles rendent les commentaires vraiment importants plus difficiles à repérer.

Ni les commentaires ni la documentation ne fournissent une sorte de mesure ou de garantie de la qualité du code qu'ils décrivent; ils ne remplacent pas une véritable assurance qualité. Leur objectif est tourné vers l’avenir, c’est-à-dire dans l’espoir d’aider les personnes qui interagissent avec elle à éviter les erreurs.

En résumé , vos normes de codage peuvent et doivent nécessiter une documentation (des contrôles automatisés aident à repérer des fonctions / méthodes non documentées, mais les utilisateurs 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 ce que sera le commentaire important à l’avance.

Mais vous voulez toujours vous assurer que le code est commenté correctement, car il s'agit d'un code essentiel à la vie. La solution consiste à avoir une norme pour la révision du code - vous devez obliger ce dernier à commenter la compréhensibilité.

Cela ne garantira pas qu'elle ne deviendra pas une liste de contrôle dénuée de sens, mais cela l'empêchera au moins de rendre le code plus difficile à lire. Et a la possibilité de le rendre meilleur.

Cela nécessite une culture dans laquelle une révision de code n'est pas en soi un geste dépourvu de sens, où obtenir votre code renvoyé aussi difficile à lire est une bonne chose, et non une insulte ou une gêne. Il est tout aussi important de ne pas considérer le lecteur comme un échec.

Le code illisible est, dans une certaine mesure, inévitable. Parce que l'écrivain est plongé dans le contexte et qu'il verra quelque chose d'aussi évident que si c'est évident si vous connaissez x, y ou z.

Donc, vous ne pourrez pas avoir une règle qui dit de donner de bons commentaires, mais vous pouvez vérifier les critiques. Même un gestionnaire non programmeur pouvait le faire - car la vraie question n'était pas de savoir si le code était lisible, mais plutôt de le lire, ce qui ne peut être décidé que par quelqu'un qui le lit.

Commenter chaque ligne de code? Non .

Les autres règles dont vous parlez ont précisément pour but d'éviter cela.

Les commentaires sur un code lisible sont au mieux redondants et, au pire, dérangent le lecteur en recherchant le but inexistant du commentaire.

Si vous commentez tout le code qui se passe d'explications, vous doublez la quantité de lecture sans donner d'informations supplémentaires. Je ne sais pas si une telle redondance serait rentable. On peut imaginer un critique qui dit que 42 dit " display_error" alors que le commentaire dit "affiche un avertissement". Mais imaginez un changement de code. Vous avez deux endroits à corriger maintenant. Il devient clair que ce style a des négatifs copier-coller.

Je dirais qu'optimalement, le code ne devrait pas nécessiter de commentaires autres que de la documentation.

Il y a des styles qui vont totalement à l'opposé, si vous avez des doutes sur la ligne c'est:

1. Le code est trop compliqué et doit être transformé en une fonction avec un nom avec une signification sémantique pour la portion de code. Que ce soit un complexe ifou une partie d'un algorithme. (Ou un ingénieux LINQ one-liner)

2. Si cela ne peut pas être simplifié, vous ne connaissez pas assez d'idiomes de langage.

(Personnellement, je ne suis pas un fanatique de la règle de non-commentaires stricte, mais je le trouve comme un bon état d'esprit initial.

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée?

En ce qui concerne le processus. Notre standard a donné beaucoup de crédit à l'examinateur. En supposant qu'ils ne soient pas malveillants, cela fonctionne bien.

Quand il demande "Qu'est-ce que la variable o?", Vous le renommez. S'il demande ce que fait ce blocage, refactoriser ou commenter. S'il y avait 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. Dans de très rares occasions, il y avait quelque chose comme 2ème opinion de peu d'amis.

En moyenne, vous devriez obtenir un code compréhensible par le programmeur moyen de l'équipe. OMI empêche les informations redondantes et veille à ce que le code soit compréhensible par au moins un autre membre de l'équipe, ce qui nous a permis de trouver un bon optimum.

En outre, il n'y avait pas d'absolu . Bien que nous soyons un petit groupe. Il est facile de trouver un consensus dans un groupe de 5.

La question:

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée? Celles qui seront pertinentes dans une évaluation par les pairs mais ne se transformeront pas en une activité insensée dans la liste de contrôle produisant des notes tout aussi 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 qu'il exit()va quitter l'application - rendant ainsi le commentaire redondant:

/* Exit the application */
exit();

Les commentaires redondants constituent une violation de DRY, et les modifications apportées au code ne sont pas nécessairement répercutées sur les commentaires, les commentaires ne reflétant pas ce que le code est en train de faire.

Cependant, les commentaires expliquant pourquoi vous faites quelque chose peuvent être utiles, surtout si vous ne pouvez pas facilement communiquer le sens dans le code lui-même.

PEP 8 de Python (guide de style pour Python dans la bibliothèque standard CPython) fournit les instructions suivantes 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 déclaration. Les commentaires en ligne doivent être séparés par au moins deux espaces de la déclaration. Ils devraient commencer par un # et un seul espace.

Les commentaires en ligne sont inutiles et, en fait, distrayants s’ils énoncent une évidence. Ne fais pas ça:

x = x + 1                 # Increment x

Mais parfois, cela est utile:

x = x + 1                 # Compensate for border

Étant donné un tel exemple, je préfère personnellement aller plus loin et essayer d'éliminer également ce commentaire. Par exemple, je pourrais arriver à:

border_compensation = 1
compensated_x = x + border_compensation

Rendre votre code auto-documenté n'est pas une idée nouvelle .

Retour à la question réelle:

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée?

Je crois que les conseils et l'exemple de PEP 8 illustrent une bonne norme de codage qui reflète cette idée. Alors oui, je crois que c'est possible.

Je pense que lorsque vous voyez ce genre de commentaire, et que j'écris moi-même 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 par ses fonctionnalités requises plutôt que par ses fonctionnalités réelles (afin que les erreurs puissent être repérées), nous parlons réellement de la manière dont les spécifications sont définies, documentées et liées. le produit final?

modifier ----

Juste pour clarifier. Je ne vais pas entrer dans les commentaires vs TDD vs tests unitaires qui 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, une norme de codage sur les commentaires serait-elle mieux écrite comme une exigence de document de spécification?

c'est-à-dire que les commentaires servent à expliquer le but du code, qui est également ce qu'une spécification est

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée? Celles qui seront pertinentes dans une évaluation par les pairs mais ne se transformeront pas en une activité insensée dans la liste de contrôle produisant des notes tout aussi utiles que: "Vous avez oublié de commenter la ligne 42".

Cela va évidemment au-delà de la documentation - cela touche à la structure du code, aux algorithmes choisis, etc. Cela peut même toucher à l'analyse et à la conception des exigences.

Ma règle n ° 1 est la suivante: "Ne documentez pas l'évidence." La règle n ° 2 est "Écrire un code évident".

Pour les codes critiques pour la sécurité (sur lesquels je n’ai jamais eu à travailler, Dieu merci), c’est un premier pas nécessaire mais loin d’être suffisant. Il faudra peut-être même décider d’indiquer quelles fonctionnalités linguistiques doivent être évitées (j’ai déjà vu plus d’une norme imposant de ne pas utiliser le logiciel scanf( "%s", input ); pour quelque raison que ce soit ).

La meilleure pratique pour le code auto-documenté n'est pas un consensus général - bien qu'il soit largement admis qu'un code facile à comprendre est meilleur qu'un code cryptique, tout le monde n'est pas d'accord sur le fait de savoir si un code compliqué doit toujours être refactoré ou s'il est acceptable de commenter. il.

Mais ce débat porte sur des éléments de code difficiles à comprendre - et vous parlez de commenter chaque ligne de code. Les lignes de code difficiles à comprendre devraient être très rares - si la plupart de vos lignes sont aussi compliquées que celles que vous utilisez trop, vous devez vous arrêter! Bien sûr, le rôle d’une ligne peut parfois être un peu difficile à comprendre, mais c’est son rôle dans le contexte d’un morceau de code plus volumineux - ce que la ligne elle-même fait est presque toujours simple.

Donc, vous ne devriez pas commenter de lignes, vous devriez commenter des morceaux de code. Des commentaires spécifiques peuvent être placés près des lignes auxquelles ils font référence, mais ces commentaires font toujours référence au code plus gros. Ils ne décrivent pas ce / pourquoi la ligne le fait - ils décrivent ce qu'il fait dans ce code et / ou pourquoi est-ce nécessaire dans ce code.

Ainsi, ce ne sont pas les lignes qui doivent être commentées, mais des morceaux de code plus gros. Est-ce que chaque morceau de code doit être commenté? Harold Abelson a déclaré: "Les programmes doivent être écrits pour que les gens puissent les lire et, accessoirement, pour que les machines puissent les exécuter ". Mais les commentaires ne sont lus que par les gens - la machine ne les exécute pas. Si vos normes de codage imposent la rédaction de commentaires redondants sur chaque ligne / morceau de code, vous ne faites pas seulement peser le développeur sur celui qui doit les écrire: vous chargez également les développeurs qui devront les lire !

C'est un problème, car lorsque la plupart des commentaires que vous lisez sont redondants, vous cessez de leur prêter attention (car vous savez qu'ils ne seront que du courrier indésirable), et vous raterez ensuite les commentaires importants . Donc, je dis - écris seulement 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 pour comprendre le code.

IMHO il devrait faire les deux. Commenter chaque ligne est idiot, parce que vous vous retrouvez avec des lignes comme

  i++;    /* Increment i */

avec absolument aucune idée de la raison pour laquelle vous souhaitez augmenter i. Développez-le un peu, et vous avez le style typique de commentaires Doxygen, qui produit une grande quantité de verbiage sans donner aucune idée de l’utilité du code ni de son fonctionnement. (Au moins autant que j'ai jamais vu: j'avoue qu'il serait peut-ê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 un groupe logique), décrivant à la fois ce qui doit être accompli et comment, s'il est moins évident, vous avez quelque chose d'utile. Si vous êtes moi-même, vous pouvez même inclure du code LaTeX pour des équations pertinentes ou des références à des articles, par exemple "Ceci implémente un schéma WENO pour la résolution des équations de Hamilton-Jacobi, comme indiqué dans ...".

Il est temps de ramener les organigrammes! (pas vraiment mais attendez une minute)

L'autre jour, j'ai retrouvé mon ancien modèle d'organigramme. Je ne l'ai utilisé que pour les devoirs et les blagues (il faut aimer un bon organigramme stupide). Mais même à ce moment-là, la plupart des programmeurs commerciaux qui utilisaient encore des organigrammes les généraient automatiquement à partir du code (ce qui remettait complètement en cause l'objectif initial de l'organigramme, qui consistait à faciliter l'écriture d'un meilleur code et était très utile en code machine. Cependant, avec les langages de niveau supérieur, l’organigramme est passé de béquille à hoble. Pourquoi? L’abstraction de l’organigramme est identique à celle du code. Les commentaires affichés sont gênants car ils sont au même niveau d’abstraction que le code. Les bons commentaires ont un niveau d'abstraction différent de celui du code, le plus simple consiste à utiliser des commentaires pour «pourquoi» alors que le code gère quoi.

Je vais répondre à la question comme indiqué:

Compte tenu de tout cela, est-il même possible d’écrire de bonnes normes de codage qui reflètent cette idée?

Oui. WYSIWYG. Une bonne norme de codage est littéralement "il est clair pour le lecteur ce que le code suivant fait et pourquoi ".

En d’autres termes, mes commentaires de révision de code sur la lisibilité du code, 1-1, découlent de mon état mental de

En tant que lecteur (mieux encore, en tant que norme minimale, modèle mental d'un lecteur moins expérimenté mais raisonnable), je ne comprendrais pas le but du code suivant ni sa méthode de travail.

En général, les gens sont faciles à comprendre "cela nécessite plus de lisibilité" quand ils entendent "moi, en tant que développeur senior que vous considérez, espérons-le, comme n'étant pas idiot, je n'ai pas au début lu le code, ni pourquoi il est là ou quoi que ce soit fait, il faut donc l'expliquer ".

Cela fait passer le discours de "vous n'avez pas suivi de norme dénuée de sens" à "votre code a un déficit de lisibilité spécifique conduisant à un problème pratique ".

Une deuxième norme qui doit être explicite est le "test d'urgence de 2 heures du matin".

Votre sauvegarde, qui n’a pas d’expérience avec ce code, peut-elle comprendre le problème du code lorsqu’il est débogué pendant un appel d’urgence au pont 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 aléatoire qui devrait être celui qui débogage la nuit en cas d'urgence de production et demandez-leur d'expliquer comment le code non commenté fonctionne et pourquoi il est Là.

Cette réponse couvre la plupart des problèmes, mais il y a une chose importante.

J'aimerais capturer une idée dans le sens de: considérons un commentaire pour chaque ligne, séquence, instruction, section, structure, fonction, méthode, classe, package, composant, ... du 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 judicieux 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 lecteurs de la documentation vous en seront reconnaissants.

La plupart des réponses existantes sont bien détaillées, mais j’ai jugé important de répondre:

... [commentaires] qui seront pertinents lors d'une évaluation par les pairs mais ne se transformeront pas en une activité insensée dans la liste de contrôle ...

Pour moi, il est possible de répondre aux seuls commentaires qui pourraient être une norme en demandant quels commentaires sont remarqués lorsqu'ils sont manquants . En d'autres termes: commentaires utilisés par les IDE ou les logiciels de documentation.

Cela étant dit, ceci est subjectif par rapport aux outils utilisés par les développeurs, et tous les commentaires utilisés par ces logiciels ne sont pas aussi utiles les uns que les autres .