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

142

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

confits_orange
la source
21
Les commentaires ne sont pas pour une discussion prolongée; cette conversation a été déplacée pour discuter .
maple_shaft
32
«Les commentaires ne sont pas destinés à une discussion prolongée», encore plus vrai pour les commentaires de code. :) Ces /* Display an error message */commentaires sont horribles et ont un impact sur la lisibilité.
Andrea Lazzarotto
Nous avons besoin que nos IDE disposent d'options pour cacher des commentaires. Peut-être une option pour les commentaires de bloc et les commentaires en ligne se cachant séparément. De cette façon, vous avez le meilleur des deux options. Mettez beaucoup de commentaires dans, mais vous avez la possibilité de les masquer pour garder le code propre et épuré.
Doug.McFarlane
1
@ Doug.McFarlane Je pensais que cela devrait exister pour Vim. Bien sûr, il le fait aux niveaux fichier et bloc - rtfm-sarl.ch/articles/hide-comments.html !
Michael Durrant
1
Alternance également - stackoverflow.com/a/11842371/631619
Michael Durrant

Réponses:

171

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.

Doc Brown
la source
45
Qui a rétrogradé cela? C'est la réponse pour le développement logiciel critique. C'est un monde différent de celui où travaillent la plupart des programmeurs. Dans ces mondes, une norme de codage qui demande que chaque ligne de code ait son propre commentaire n'est pas la bonne réponse. Ni est renoncer à des commentaires. OTOH, soumettre les commentaires à la révision du code est exactement le bon type de norme pour les logiciels critiques. Il en résulte un code plus révisable et maintenable, mais cela a un coût. Ce coût est minime comparé aux procès de plusieurs millions de dollars résultant de logiciels mal écrits.
David Hammen
4
réponse sage. si nous pouvions trouver de véritables règles de codage, nous n'aurions pas besoin de programmeurs. nous pourrions simplement avoir le code des machines. ça pourrait arriver! :(
4
@ David Hammen: merci pour votre commentaire. En fait, je pense que cela ne s'applique pas seulement au "développement logiciel critique". Chaque logiciel élémentaire mis à jour et développé au fil des ans, souvent par des personnes différentes, aura tout intérêt à être compréhensible pour le prochain programmeur de maintenance.
Doc Brown
5
C'est un bon conseil pour tout codage, pas seulement pour le code maintenu par différentes personnes. Même si vous êtes le seul à utiliser un script / programme, les futurs utilisateurs qui devront modifier le code dans un an apprécieront la clarté (et le gain de temps en évitant de déchiffrer le code opaque).
Anthony Geoghegan
5
Pourriez-vous éditer "réponse actuellement la plus votée" à quelque chose de plus objectif? Tous les lecteurs ne connaîtront pas l'historique des votes de ces réponses.
candied_orange
151

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

Michael Durrant
la source
8
Je ne crois pas que vous ayez répondu à la question. La question n’est pas d’avoir des commentaires sur chaque ligne. Il demande comment dire aux développeurs de commenter le code sans les obliger à commenter chaque ligne.
hichris123
7
Oui, je ne réponds pas à la question des normes spécifiques mais j'essaie plutôt d'aider les gens à ne pas suivre cette voie. Donc, ce n'est peut-être pas la réponse à la question spécifique, mais contient des conseils précieux qu'il est difficile de donner dans un commentaire.
Michael Durrant
1
Quel est l'autre problème difficile?
David Grinberg
20
@DavidGrinberg invalidation du cache et erreurs off-by-one .
Eric King
1
Chacune de vos raisons d'éviter les commentaires peut être contrée, mais StackExchange ne permet pas suffisamment de commentaires (heh) pour que je puisse les aborder tous ici. Simplement: le dépassement est comme une fraude électorale: cela se produit, mais très rarement; quelle est la dernière fois que vous l'avez vu arriver? Ecrire de bons commentaires ne devrait pas être simplement une réflexion après coup; si cela est fait correctement, cela aide le processus de développement. Oui, cela prend des ressources, mais le gain est meilleur que le code. Vous ne pourrez jamais obtenir le même rendement en sacrifiant les commentaires pour une meilleure norme de nommage des variables. Oui, commenter chaque ligne est fou.
kmoser
23

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.

JacquesB
la source
63
Une des nombreuses choses que j'ai apprises après plus de 40 ans d'expérience dans ce secteur est que le bon sens n'est pas du tout commun.
John R. Strohm
10
Le sens commun n'existe pas.
Whatsisname
1
in_programming no .. monde réel oh oui mais c'est juste un terme pour la connaissance expérimentée du monde réel
Michael Durrant
@ JohnR.Strohm: Mon expérience a été beaucoup plus positive que la vôtre, mais j'ai aussi vu comment l'utilisation du bon sens peut être activement découragée par l'application mécanique de règles.
JacquesB
Je suis d'accord à 99,9% avec cette réponse. La norme de codage est censée être l’objet que les développeurs soulignent lors d’un débat lors de la révision du code. La révision de code vise à enrichir le produit et non à déclencher des guerres. J'ai vu tellement de guerres avoir été initiées par des revues de code sans norme de codage. J'ose dire que si vous ne pouvez pas automatiser la vérification des éléments de la norme de codage, elle devrait y figurer. Une révision du code est le moment idéal pour donner du «bon sens» à d'autres développeurs moins expérimentés. Ce n'est pas le moment de se battre pour nommer les variables. linux / kernel / gen_init_cpio.c ligne 335.
Andrew T Finnell
19

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.

comment s'appelle-t-il
la source
1
+1 pour "Vous essayez de mécaniser le bon jugement", -1 pour "Votre seule option est simplement d'espérer le meilleur", ce qui me laisse ne pas voter. Eduquer et former votre équipe est également une option. Les normes peuvent permettre un jugement.
Wildcard
1
@Wildcard Peut-être pourriez-vous expliquer comment une norme peut permettre un jugement? Ne serait-ce pas un guide à ce stade? Une norme est "une idée ou une chose utilisée comme mesure, norme ou modèle dans les évaluations comparatives". Comment utiliser quelque chose intrinsèquement subjectif, donc subjectif, cela dépend de qui le lit, comme mesure de la qualité?
Andrew T Finnell
1
@Wildcard: Le problème est que, lorsque vous entrez dans des industries réglementées, le processus règne en maître sur tout, un processus est plus important que de savoir si le processus en vaut la peine ou pas. Tout doit se résumer à des cases à cocher dans un formulaire, chaque case à cocher doit être spécifique et vérifiable, et plus vous avez de marge de manœuvre, moins vous risquez de vous faire bousiller dans un audit.
Whatsisname
C’est un monde étrange, et gardez à l’esprit que les règles sont écrites par des bureaucrates peu familiarisés avec le domaine des logiciels, et que vous vous retrouvez souvent avec des systèmes qui existent pour se justifier et s’exiger eux-mêmes plutôt que comme un moyen de garantir des produits de qualité.
Whatsisname
1
@whatsisname Je suis très heureux qu'il y ait quelqu'un d'autre qui comprend. Vos réponses sont écrites avec plus d'élégance et de précision que je n'aurais pu m'efforcer. La déclaration with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsest EXACTEMENT ce que je tentais d’illustrer. Merci d'avoir trouvé mes mots pour moi. Je le pense vraiment. Nous devons séparer l'idée d'induire la qualité de celle de suivre un processus, car ils ne sont pas les mêmes. C'est pourquoi nous avons l'assurance qualité, Stackoverflow et des clients très indulgents.
Andrew T Finnell
14

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.

Andrew T Finnell
la source
3
Le problème avec les commentaires est qu’ils n’ont AUCUN impact sur le fonctionnement final du produit. Eh bien, si la partie humaine de la lecture et de l’écriture du code compte, je pense que cela a une incidence sur son fonctionnement final , mais pas sur la façon dont le code s’exécute à la fin de l’écriture, oui. Je dirais que le problème avec le code, c'est simplement qu'il devient obsolète et que c'est pire que pas de code!
Michael Durrant
1
Ici, nous avions un chronométreur qui voulait des rapports quotidiens sur ce que nous faisions afin d’optimiser notre travail. Dans tous les cas, nous étions un peu fâchés du fait que nous devions passer 15 minutes chaque jour à remplir son formulaire. Nous avons donc automatisé le processus en remplissant les ordures de nos journaux.
Joojaa
1
Il y a un problème supplémentaire avec le commentaire "Nous ne divisons pas par 0 pour éviter les accidents." On ne sait pas grammaticalement si la clause "pour commander" s'applique à l'action de division ou à sa négation. Si vous utilisez "Nous évitons de diviser par 0 pour ...", vous évitez cette ambiguïté. :)
Wildcard
1
"ne pas diviser par zéro pour éviter les accidents" en dit long sur l'état d'esprit de celui qui l'a écrit. Vous ne codez pas pour éviter les plantages! Vous codez pour que le code soit correct, et que ne pas planter ne soit qu'une petite partie de l'exactitude. Si le calcul de la quantité de médicament à injecter finit par diviser par zéro, vous ne renvoyez pas de valeur fictive telle que 99999 ...
immibis
1
@ AndrewTFinnell Je veux dire que si vous obtenez parfois une erreur division par zéro, l'ajout de "if (diviseur == 0) renvoie <quelque chose; // éviter la division par zéro" ne rend pas votre code plus correct. Au lieu de cela, vous devez rechercher pourquoi le diviseur est égal à zéro et résoudre ce problème. Certains algorithmes sont conçus pour que le diviseur nul soit inévitable, mais ils sont l'exception (et dans ce cas, vous pouvez renvoyer une valeur "le résultat ne peut pas être calculé").
Immibis
12

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.

utilisateur52889
la source
Documenter l'API publique est un bon point, mais j'aime beaucoup expliquer les décisions surprenantes. C'est très bien si les violations du principe de moindre étonnement viennent au moins avec une justification. +1
candied_orange
1
+1 pour les commentaires parasites sous forme de bruit. Gardez le signal au bruit élevé.
sq33G
+1 spécialement dans le but d'un commentaire est vaincu si chaque ligne est commentée. Dommage que cela puisse être (et est souvent) utilisé comme une excuse pour ne pas commenter du tout, mais c'est quand même très correct, pour les raisons que vous avez mentionnées plus car, si chaque ligne est commentée, la plupart des gens commenceront automatiquement et naturellement à ignorer tous les commentaires. .
SantiBailors
10

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.

jmoreno
la source
7
Re Vous ne pouvez pas codifier une norme de commentaires - Bien sûr, vous le pouvez. Vous soumettez les commentaires à une révision de code, et cet élément de révision de code indiquant que les commentaires n'expliquent pas le code doit être adressé. C'est une dépense, une dépense que la plupart des environnements de programmation ne veulent pas payer. C'est payant en ce qui concerne les logiciels critiques.
David Hammen
"... quand c'est évident seulement si vous savez x, y ou z" Vous pouvez spécifier la quantité de connaissances {x, y, z} qu'il faut connaître à l'avance pour voir quelque chose d'aussi évident et ensuite (genre mécaniquement), vous pouvez vérifier si cela est vrai pour le code actuel. Où pas, ajoutez des commentaires jusqu'à ce qu'il soit.
Trilarion
1
@ David Hammen: ce n'est pas une norme pour le commentaire, c'est une norme pour l'examen. C’est ce que j’ai suggéré comme solution. Vous ne pouvez pas dire qu'il doit avoir une certaine taille, utiliser une syntaxe particulière ou même utilement demander un commentaire (ou obtenir des commentaires de type "add one to i"). Vous POUVEZ dire que le réviseur doit commenter le code et les commentaires. Comme vous le dites, vous pouvez exiger que les problèmes soulevés par la révision du code soient résolus. Mais il incombe à cet auteur de faire du bon travail. Seul le relecteur peut juger si le code et le commentaire sont suffisants.
Jmoreno
@DavidHammen Les personnes choisies pour l'examen font appel au jugement? Et quand ils partent? Si les nouvelles personnes ne pensent pas de la même façon ou ne parlent pas anglais? Si les 'examinateurs' partent? Votre suggestion place quelques développeurs au sommet d’une tour d’ivoire, ce qui conduit à la dissidence, à la méfiance et à une rupture de la communication. Les commentaires ont pour but de fournir un aperçu ou une clarification à ceux qui peuvent l’utiliser. Peut-être que Joe en a besoin mais pas Mary. Que se passe-t-il quand Marie est la critique? Ou Joe? Ou Mark?
Andrew T Finnell
@jmoreno - Si les normes de codage ne sont pas soumises à des règles / directives sur les commentaires, les programmeurs doivent consulter plusieurs sources - et ils ne savent pas où regarder avant que l'examen ne revienne, affirmant que certains commentaires sont inférieurs aux normes. C'est une erreur de penser que tout dans une norme de codage doit être automatisable. Les règles sur les noms significatifs, par exemple, ne sont pas automatisables. Au moins pas encore. Par exemple, x, yet z, ou i, jet kpeuvent être des noms tout à fait significatifs si l' on met en œuvre un algorithme scientifique basé sur un papier journal qui a utilisé exactement les noms dans ses formules.
David Hammen
9

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.

luk32
la source
2
Utiliser les révisions de code pour dicter quelles variables, classes et méthodes doivent être nommées est le meilleur moyen d'inciter les gens à haïr une entreprise, une entreprise ou une méthodologie. Les révisions de code ne doivent pas être utilisées comme un moyen de faire appliquer des choses qui ne comptent pas vraiment. Une norme de codage doit pouvoir être vérifiée via un processus automatisé. La longueur du nom de la variable, la complexité circulaire, la loi de Demeter, sont toutes des choses qui peuvent être vérifiées. Si quelqu'un me disait de renommer une variable de «i» à quelque chose comme indexForThePreviousCollection, je trouverais un autre lieu de travail. Les variables> 3 caractères sont toutes vérifiées avant l'enregistrement automatique.
Andrew T Finnell
3
@AndrewTFinnell Je peux écrire un code impossible à suivre dans tous les paradigmes de programmation que vous souhaitez nommer.
candied_orange
2
@ AndrewTFinnell Eh bien, je vais poliment ne pas être d'accord. " Utiliser les revues de code pour dicter ", je ne sais pas d'où vous l'avez tiré. Je ne voudrais pas travailler sur le code des variables i, j, kdans le lieu après l'auteur original se ferme. Je ne comprends pas votre argument sur le génome "humain". Je doute qu'il y ait une langue dans laquelle une déclaration est unique ou deux sont trop difficiles à comprendre. Comme je l'ai dit, j'ai vu des ifs complexes et des LINQone-liners. Ils peuvent être commentés ou refactorisés sous un nom sémantiquement significatif, je suppose que c'est votre "bon commentaire".
Louk32
3
@ luk32 Je respecte le droit de ne pas être d'accord. Les variables d'itération sont très contextuellement évidentes à mon avis. Bien que je comprenne le sentiment de votre déclaration, je crois qu’il ya trop de pratiques qui le portent à l’extrême. Avons-nous vraiment besoin de code qui lit: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)par rapport for (int i = 0; i < results.length; i++)? C'est peut-être une question de préférence et / ou de temps passé à regarder le code. Les noms trop verbeux sentent pour moi.
Andrew T Finnell
2
Je ne pense pas que les noms devraient être décidés dans les revues de code. La révision du code doit généralement commencer après que l'auteur a jugé que c'est assez bon, ce qui signifie également qu'il est correctement commenté, facile à comprendre et que les variables ont des noms décents. Le problème est le suivant: si les réviseurs pensent que le code est trop compliqué ou s’interrogent sur le sens d’une variable, il est difficile à comprendre. Ce n'est pas discutable - évidemment au moins un développeur - le relecteur - ne l'a pas compris. Que ce soit ou non doit être refactorisé (et comment) ou correctement commenté est une question différente.
Idan Arye
9

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.

Aaron Hall
la source
1
"Un lecteur devrait être supposé connaître la langue mieux que l'écrivain" J'ai du mal à croire que c'est la bonne attitude. Je peux voir en supposant qu'ils en savent autant , mais chaque équipe est différente, et chaque membre d'une équipe est différent, de sorte qu'une déclaration générale sur ce point particulier ne semble pas judicieuse.
Bryan Oakley
4
Sans cette aide, les programmeurs débutants commettront des commentaires expliquant le code trivial à personne autre qu'eux-mêmes, et les programmeurs de niveau intermédiaire utilisant des solutions peu pratiques simplement pour rendre le code plus accessible aux programmeurs débutants. Ce guidage élimine la redondance et garantit que même un programmeur compétent continue à améliorer son code. Lorsque je revisite le code moi-même, j'ai peut-être oublié le contexte, mais en général, je sais ce que le langage fait encore mieux que lorsque je l'avais écrit pour la première fois.
Aaron Hall
4

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

Ewan
la source
6
En 20 ans, je n'ai jamais vu quelque prototype prototyper leur code de cette façon, puis combler les lacunes avec le code réel. Il existe déjà un moyen objectif de réaliser ce que vous dites ou ce que je pense que vous dites. C'est ce qu'on appelle le développement piloté par les tests. Les tests unitaires définissent la spécification et déterminent si le code y adhère. Tous sans commentaires.
Andrew T Finnell
9
Bien que je ne pense pas que le code dans la question soit un bon exemple de cela, la pratique d'écrire d'abord une procédure dans les commentaires, puis de revenir en arrière et de remplir le code est spécifiquement appelée dans "Code complet". pratique possible pour aider à produire du code lisible, @AndrewTFinnell. Ce n'est certainement pas du jamais vu, même si cela sort de votre expérience.
Josh Caswell
6
Je crois aussi avant le tdd
Ewan
2
Parlez-vous du processus de programmation pseudocode? Le but de cela était de réduire les commentaires. Je ne me souviens jamais de ce livre indiquant que les commentaires devraient être laissés dans le code. Et commenter pour produire une procédure conceptuelle est censé être de haut niveau, pas de bas niveau. Si l'on devait commenter chaque ligne qu'ils avaient l'intention d'écrire, ils auraient pu simplement écrire les lignes. L'idée est de prototyper les principes du code et non chaque ligne. Le livre ne suggère pas de commenter chaque ligne. C'est le centre de cette question. Et je peux me tromper, mais je crois que c'est dans la deuxième édition.
Andrew T Finnell
2
@JoshCaswell & Ewan, oui il était il y a plusieurs années une technique et ne fait TDD datent d' avant. Mais vous étiez censé supprimer les commentaires par la suite! Et TDD l’a complètement supplantée en tant que moyen judicieux de créer un code conforme à une spécification.
David Arno
4

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 ).

John Bode
la source
C'est évident dans l'œil du spectateur. Et change en fonction de la date limite.
Tony Ennis
3

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.

Idan Arye
la source
1
Ne manquez pas les commentaires importants: +1. La phrase qui commence par: "Ils ne décrivent pas" pourrait utiliser une restructuration pour la rendre plus facile à suivre.
candied_orange
3

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 ...".

Jamesqf
la source
2
+1 pour le commentaire doxygen: C’est précisément mon objection à inclure la "documentation" de doxygen dans mon code; 95% du temps, il répète simplement ce qui est déjà évident depuis la signature de la fonction. Moi aussi, je n'ai pas encore vu de documentation doxygen qui vaille la peine. Écrire ces commentaires fait perdre du temps à trois reprises: une fois pour écrire les commentaires, une fois pour les relire et une fois pour résoudre les problèmes créés par le contenu obsolète des commentaires.
cmaster
1
Tu ne te contredis pas? Je pense que nous convenons tous les deux qu’il est essentiel pour une fonction d’avoir un commentaire décrivant ce qu’elle fait du point de vue de la boîte noire: «ces entrées sont intégrées, la fonction agit, et ces sorties sont affichées». Il constitue le contrat entre la personne qui a écrit la fonction et les personnes qui l'utilisent. Le but de Doxygen est simplement de normaliser le format de ces commentaires de manière à pouvoir être analysés et rendus consultables / indexables. Alors, pourquoi voudriez-vous un "bon bloc de commentaires" sans le vouloir dans un format standard, lisible par l'homme et par la machine?
Graham
L’utilisation d’une norme de commentaire telle que JSDoc, JavaDoc et Doxygen permet de fournir une documentation lisible par un utilisateur et lisible par l’homme, comme @Graham l’a dit. La ligne de code mentionnée dans cette réponse n'a rien à voir avec Doxygen. Je ne peux même pas imaginer un ensemble de règles en place qui analyserait ce commentaire et produirait une entrée dans la documentation fournie. Lorsque vous examinez la documentation pour JMI, les bibliothèques standard Java, etc., elles sont toutes produites à l'aide d'un outil très similaire à Doxygen. C'est le but de cela. Pas ce qui est dit ici
Andrew T Finnell
Je ne fais pas cela - pour répondre à une exigence canadienne, une entreprise dans laquelle je travaillais avait demandé aux développeurs d’écrire un pré-processeur qui ajoutait des commentaires EXACTEMENT comme l’exemple de l’OP. Je pense que le nôtre était "C ADD 1 TO I" ou quelque chose comme ça. C'était FORTRAN, donc les boucles ont été recommandées de la même manière "C LOOP DE 1 À 10". Le code a été chargé avec des commentaires inutiles. J'ai supprimé toute cette merde que j'ai maintenu le code. Personne ne m'a jamais rien dit.
Tony Ennis
2

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.

Hildred
la source
Je suis désolé de vous informer que les organigrammes ne sont jamais partis.
Ant P
Les bons commentaires ont un niveau d'abstraction différent de celui du code . Entendre entendre!
candied_orange
1
Bien que cela puisse être un conseil décent, il ne semble pas répondre à la question qui a été posée, à l'exception peut-être d'une seule phrase.
Bryan Oakley
0

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à.

DVK
la source
0

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.

BЈовић
la source
1
Mais la "documentation" générée par ces outils vaut, du moins selon mon expérience, généralement moins que pas de documentation du tout, car elle ne fournit pas à l'utilisateur d'informations utiles (et les fait perdre du temps à essayer d'extraire le informations existantes), mais permet aux développeurs de croire qu’ils ont correctement documenté leur code.
Jamesqf
@jamesqf Oui, quand la moitié des fonctions ne sont pas documentées et l'autre moitié mal. Cependant, doxygen peut générer une assez bonne documentation, en supposant que les développeurs aient correctement commenté leurs fonctions, leurs classes, etc.
dimanche
-1

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 .

Erdrik Ironrose
la source