Pourquoi oncle Bob suggère-t-il que les normes de codage ne soient pas écrites si vous pouvez les éviter?

Pendant que je lisais cette question , la réponse la plus votée citait Oncle Bob sur les normes de codage , mais cette astuce me laissait perplexe:

3. Ne les écrivez pas si vous pouvez l'éviter. Laissez plutôt le code être la manière dont les normes sont capturées.

Cela a rebondi dans mon cerveau, mais je n’ai pas pu trouver un endroit où coller. Si une nouvelle personne se joint à l'équipe ou si les normes de codage changent, ne pourrait-il pas y avoir confusion des informations?

Pourquoi ne devrais-je pas écrire une norme de codage?

Il y a quelques raisons.

1. Personne ne lit la documentation.
2. Personne ne suit la documentation même s’ils la lisent.
3. Personne ne met à jour la documentation, même s’ils la lisent et la suivent.
4. Écrire une liste de pratiques est beaucoup moins efficace que de créer une culture.

Les normes de codage ne traitent pas de ce que les gens devraient faire, mais de ce qu'ils font réellement . Lorsque les utilisateurs s’écartent des normes, cela devrait être pris en compte et modifié grâce à un processus de révision du code et / ou à des outils automatisés.

N'oubliez pas que le but des normes de codage est de nous faciliter la vie. Ils constituent un raccourci pour notre cerveau afin que nous puissions filtrer les éléments nécessaires des éléments importants. Il est bien préférable de créer une culture de contrôle pour le faire respecter que de le formaliser dans un document.

Il y a une autre interprétation. Je ne crois pas que ce soit ce que voulait dire Oncle Bob, mais cela vaut la peine d'être examiné.

Ne capturez pas les normes de codage dans un document. Capturez-le en code, en ayant un processus automatisé qui vérifie que les normes sont respectées .

Ne vous fiez pas aux gens qui référencent un document, mais en même temps, ne comptez pas sur ceux qui interprètent le code existant et identifient ce qui est conventionnel et ce qui est une coïncidence.

Incorporez quelque chose comme Checkstyle dans votre build de commit. Cela peut appliquer les règles de base telles que les normes de formatage et de nommage, et au lieu de déployer des efforts considérables en matière de style, tout cela peut être transféré à un processus stupide, dont au moins la garantie d'être minutieuse.

Si cela compte, définissez strictement ce que vous voulez et échouez si cela ne va pas.

Les gens négligent le véritable objectif d'un document de normes de codage, à savoir le règlement des différends .

La plupart des décisions de la norme de codage n'auront qu'un effet très mineur sur la lisibilité et la productivité. Surtout si vous adoptez le style «normal» pour le langage et que les concepteurs de langage commencent à se rendre compte que cela devrait faire partie de la spécification (par exemple, Go).

Parce qu'ils sont si triviaux, les arguments peuvent être très difficiles à comprendre et à courir sans fin, ce qui nuit considérablement à la productivité et à la cohésion de l'équipe. Ou encore, obscurcissez votre historique des changements avec un reformatage sans fin entre les styles préférés de deux personnes ou plus.

Avoir une norme écrite met fin à la discussion. Les gestionnaires peuvent le pointer et dévier l’insatisfaction vers le document. Vous pouvez discuter avec un bout de papier, mais il ne vous écoutera pas.

(Voir aussi La tyrannie de l'absence de structure )

Parce que les commentaires sont des mensonges .

La norme de codage est un très bon commentaire sur ce que le code devrait être. Le code lui-même est la source ultime de vérité. La vérité, dans ce cas, n’est pas un comportement de code, mais le style dans lequel elle est exprimée. Si vos normes ne sont pas déjà reflétées dans votre code, vous avez beaucoup de travail à faire.

Oncle Bob considère un commentaire comme un échec personnel du programmeur, car cela prouve qu'il n'a pas réussi à exprimer l'objectif du fragment de code avec le langage de programmation lui-même. De même, un document de normes est un échec pour exprimer un style cohérent dans la base de code.

Les nouveaux programmeurs devraient passer du temps à consulter le code et non pas à lire un document de normes comportant plusieurs chapitres (j'ai dû le faire, soupir).

Un document de normes n’est pas une si mauvaise idée, mais j’ai travaillé dans des ateliers de programmation où le maintien des documents de normes était un travail à plein temps. S'il vous plaît, si vous devez conserver un document de normes, conservez-le sur une page. Mais si vous avez déjà du code, personne ne devrait-il être capable de rassembler le même document en moins d'une journée?

Avoir des normes de code est important. Avoir un document qui dicte ce qu’ils sont ne l’est pas.

Pourquoi oncle Bob suggère-t-il que les normes de codage ne soient pas écrites si vous pouvez les éviter?

Si vous demandez des raisons derrière son opinion, vous n'aurez peut-être une réponse que s'il publiera une réponse ici ( notre opinion est tout simplement sans importance), cependant ...

Pourquoi ne devrais-je pas écrire une norme de codage?

Si vous lui demandez s'il a raison, laissez-moi être le seul impopulaire (jusqu'à présent) à dire que vous n'avez aucune raison de l'éviter.

ECRIVEZ-LE . Cependant, je vais essayer d'expliquer mes raisons ...

Dans un commentaire, David a suggéré que l'objectif principal de la réponse de Stephen n'était pas de savoir pourquoi vous ne devriez pas écrire de documents, mais sous quelle forme. Si les directives sont formalisées dans des outils (pas simplement une révision manuelle du code), je peux accepter (lorsque la loi n'exige rien d'autre). Veuillez noter que, malheureusement, les outils ne peuvent pas tout vérifier (la théorie du calcul n’est pas notre ami) souvent parce qu’ils sont limités à une unité de traduction ou à un package spécifique , ou quelle que soit votre langue préférée, appelez une limite .

Cependant, le libellé de mon oncle Bob ne me laisse pas penser qu'il en parle.

Puis-je être en désaccord avec un tel expert chevronné? Je le fais, pour presque chaque point dans le post cité (voir aussi la deuxième partie de cette réponse pour plus de détails). Essayons de comprendre pourquoi ( en supposant que vous savez déjà que les lignes directrices de codage ne sont pas seulement mineures de mise en forme des questions ).

• Dans certaines circonstances, des normes de codage écrites sont requises par la loi.
• Je lis la documentation et je suis sûr que je ne suis pas seul. Les membres de l'équipe peuvent changer avec le temps, les connaissances ne peuvent pas être dans une base de code vieille de 5 à 10 ans ni dans l'esprit des membres de l'équipe. Les organisations devraient licencier les personnes qui ne suivent pas les directives internes.
• Les normes de codage, une fois qu'elles ont été approuvées , ne changeront pas souvent et si vous voulez en savoir plus à ce sujet. Si les normes ont changé, votre documentation (en code) est obsolète car tout votre code ne suit pas la nouvelle norme. Le reformatage / refactoring peut être lent, mais vous devez toujours suivre des directives écrites faisant autorité .
• Il est préférable de lire un document de 5 pages plutôt que d'inspecter une LOC de 10 / 20K pour extrapoler une règle (que vous comprenez peut-être mal, BTW), cela ne fait aucun doute.
• Il est ironique de constater que quelqu'un qui a écrit de nombreux livres sur les principes de conception et le style de codage suggère de ne pas écrire vos propres directives. Ne faites-vous pas mieux s'il nous envoyait des exemples de code? Non, car les directives écrites vous indiquent non seulement quoi faire, mais aussi deux autres choses qui manquent dans le code: ce qu'il ne faut pas faire et les raisons de le faire ou non.

"La programmation libre et auto-organisée" est bonne pour un ninja de 16 ans, mais les organisations ont d'autres exigences :

• La qualité du code doit être garantie (et définie) au niveau de l'entreprise - ce n'est pas une tâche à décider par une seule équipe. Ils n’ont peut-être même pas les compétences nécessaires pour décider de ce qui est préférable (combien de développeurs, par exemple, ont-ils tous les compétences requises pour examiner MISRA ou même simplement comprendre chaque règle?)
• Les membres peuvent être déplacés dans différentes équipes: si tout le monde respecte les mêmes normes de codage, l'intégration est lisse et moins sujette aux erreurs.
• Si une équipe s'organise elle-même, les normes évolueront avec le temps lorsque ses membres changeront. Vous disposerez alors d'une base de code énorme qui ne respecte pas les normes actuellement acceptées .

Si vous pensez aux personnes avant le processus, je ne peux que suggérer une lecture à propos de TPS: les êtres humains sont un élément central de Lean, mais les procédures sont hautement formalisées.

Bien sûr, une petite organisation avec une seule équipe peut laisser l’équipe décider des normes à adopter, mais cela doit être écrit par la suite. Ici sur Programmers.SE, vous pouvez lire les articles d’Eric Lippert: Je suppose que nous sommes tous d’accord sur le fait qu’il est un développeur expérimenté. Lorsqu'il travaillait pour Microsoft, il devait respecter leurs consignes écrites (même si certaines règles pouvaient être erronées , non applicables ou inutiles. à lui.) Et Jon Skeet? Les directives de Google sont assez strictes (et beaucoup de personnes ne sont pas d'accord avec celles-ci), mais il doit s'y conformer. Est-ce irrespectueux pour eux? Non, ils ont probablement travaillé pour définir et améliorer de telles directives, une entreprise n’est pas composée d’un membre (ou d’une équipe) et chaque équipe n’est pas une île .

Exemples

• Vous avez décidé de ne pas utiliser plusieurs classes d'héritage et imbriquées en C ++, car les membres de votre équipe ne le comprennent pas bien . Par la suite, toute personne souhaitant utiliser plusieurs héritages doit parcourir l'intégralité du LOC 1M pour voir s'il a déjà été utilisé. C'est mauvais parce que si les décisions de conception ne sont pas documentées, vous devez étudier toute la base de code pour les comprendre. Et même dans ce cas, si cela n’a pas été utilisé, c’est parce que cela va à l’encontre de la norme de codage, ou est-ce autorisé, mais il n’y avait tout simplement pas de situations antérieures où l’héritage multiple convenait bien?
• En C #, vous aviez des méthodes surchargées pour fournir des paramètres par défaut car votre base de code a démarré lorsque des paramètres facultatifs n'étaient pas disponibles en C #. Ensuite, vous avez changé et vous avez commencé à les utiliser (refactoriser l'ancien code pour les utiliser chaque fois que vous deviez modifier de telles fonctions). Même plus tard, vous avez décidé que les paramètres facultatifs sont mauvais et vous commencez à éviter de les utiliser. Quelle est la règle que votre code vous dit? C'est mauvais parce que la norme évolue mais que codebase est plus lent à évoluer et si c'est votre documentation, vous avez des problèmes.
• Jon est passé de l'équipe A à l'équipe B. Jon doit apprendre un nouveau standard. tout en apprenant, il introduira probablement des bogues plus subtils (ou, si vous êtes chanceux, prenez tout votre temps pour comprendre le code existant et prolonger sa révision).
• L'équipe A se déplace vers une base de code précédemment détenue par l'équipe B. Elle a des normes de codage complètement différentes. Récrire? Adapter? Mélanger? Tous sont également mauvais.

Oncle Bob

Laissez-les évoluer au cours des premières itérations.

Il est vrai que tant que vous n’avez pas de norme et que votre organisation vous a confié la tâche de la construire .

Laissez-les être spécifiques à l’équipe plutôt qu’à la société.

Non, pour toutes les raisons expliquées ci-dessus. Même si vous pensez formaliser uniquement le formatage du code (la chose la moins utile que vous souhaitiez formaliser), j'ai encore en mémoire des guerres sans fin (et inutiles) sur le formatage. Je ne veux pas les vivre encore et encore, réglez-le une fois pour toutes.

Ne les écrivez pas si vous pouvez l'éviter. Laissez plutôt le code être la manière dont les normes sont capturées.

Non, pour toutes les raisons expliquées ci-dessus (bien sûr, à moins de refactoriser tout votre code en une fois lorsque les directives changent). Voulez-vous laisser votre code tel quel? Comment inspectez-vous codebase pour comprendre les directives actuelles ? Recherche par âge de fichier et adaptation de votre style de codage à l’âge du fichier source?

Ne légiférez pas un bon design. (par exemple, ne dites pas aux gens de ne pas utiliser de goto)

Certes, les directives doivent être courtes ou personne ne les lira. Ne répétez pas l'évident.

Assurez-vous que tout le monde sait que la norme concerne la communication et rien d'autre.

Non seulement, un bon niveau concerne la qualité, à moins que vous ne souhaitiez définir un standard uniquement sur des détails mineurs .

Après les premières itérations, demandez à l’équipe de décider.

Voir le premier point et ne pas oublier qu’une norme de codage est généralement un processus qui a pris plusieurs années à être développé et affiné: peu d’itérations, peut-être avec des développeurs débutants? Vraiment? Voulez-vous vous fier à la mémoire d'un membre senior (le cas échéant)?

Trois notes:

• À mon avis, les inconvénients sont plus graves avec certains langages que d’autres, par exemple en C ++, une norme au niveau de l’entreprise est encore plus nécessaire qu’en Java.
• Ce raisonnement peut ne pas s'appliquer entièrement (et les raisons données par Oncle Bob peuvent être moins extrêmes ) si vous travaillez dans une très petite entreprise où vous n'avez qu'une seule petite équipe.
• Vous êtes embauché (en équipe) et vous travaillerez seul avec un nouveau projet, vous l'oublierez et vous passerez à autre chose. Dans ce cas, vous ne vous en souciez peut-être pas (mais votre employeur devrait ...)

1. Pour être utile, une norme de codage ne doit pas traiter de questions de fond; seulement des questions de style. Il ne devrait spécifier que les éléments arbitraires et ambigus. p.ex. placement d'accolade, profondeur d'indentation, espaces par rapport aux tabulations, conventions de dénomination, etc.
2. Les questions de style sont locales et non mondiales. Chaque équipe doit adopter son propre style, adapté à sa tâche et à sa personnalité. Cela maintient les normes simples et légères. Les normes d'entreprise sont surchargées de considérations, de configurations et d'exceptions possibles.
3. Au sein d'une équipe, la seule raison d'écrire un document de style de codage distinct est si le code produit par l'équipe ne respecte pas la norme. Dans ce cas, vous n'avez pas de standard. Pour être efficace, la norme devrait être exprimée par le code lui-même. Et si tel est le cas, il n'est pas nécessaire de disposer d'un document séparé.
4. Dans les systèmes existants, les équipes et les styles changent avec le temps. Il n'y a rien de mal à ça. Ancien code aura un style plus ancien. Le code le plus récent aura un style plus récent. L'équipe doit être consciente des styles et de leur âge. Chaque fois que le nouveau code est écrit, il doit être dans le nouveau style, quel que soit son emplacement dans le code.

Pourquoi ne devrais-je pas écrire une norme de codage?

Il y a plusieurs raisons à cela. Voici quelques considérations:

1. Combien de temps les gens passent-ils "à apprendre" les normes de code pour ne pas perdre beaucoup de temps dans l'ensemble de l'équipe pour réviser, discuter, documenter, réviser, etc., les normes de code. C'est comme si vous discutiez constamment de votre "Manuel de l'employé" - à quelle fréquence cela le fait-il à l'ordre du jour d'une réunion d'équipe?

2. Lorsqu'un projet est financé / mis de côté / etc. alors les quelques personnes qui restent ne peuvent généralement pas continuer à respecter (ou peut-être même pas lu) les normes. La prochaine chose que vous savez, tous ces efforts pour "garder le code propre" a été assez gaspillée de toute façon.

3. Si le projet est bloqué ou si un nouveau chef de file est introduit, il est fort probable que cette personne ignore totalement les règles précédentes et souhaite procéder de manière différente. Encore une fois, qu’a-t-on gagné en codifiant des normes?

Vous devriez être sûr de lire # 6:

Après les premières itérations, demandez à l’équipe de décider.

En d'autres termes, lorsqu'il est temps de démarrer un projet, suivez le flux pendant un moment. Ensuite, discutez des règles générales des normes de codage utilisées par l’équipe actuelle et respectez-les. De cette façon, vous optimisez les efforts nécessaires pour améliorer le produit tout en minimisant les efforts nécessaires pour écrire, réviser et documenter le "sucre syntaxique" utilisé pour obtenir du code exécutable.

Très peu d’équipes tirent d’énormes avantages des normes de codage. Habituellement, la "lisibilité" est beaucoup trop vague - et la plupart des développeurs ne bénéficient pas de règles exactes en matière d'espacement, de nouvelles lignes, etc., mais vous pouvez éviter de gêner constamment les développeurs en ayant au moins quelques règles.

Une autre réponse qui, à mon avis, n’a pas été suffisamment clairement énoncée, est que cela signifie également que les gens ne respectent pas les règles à l’aveugle. Cela signifie que les utilisateurs doivent trouver des justifications concrètes pour leurs décisions de conception et leurs conventions de codage, plutôt que de simplement compter sur le fait que cela a été écrit pour le justifier.

Tout d’abord, pour autant que je sache, oncle Bob est une personne de Java, c’est très important pour comprendre ce qu’il dit.

Lorsque vous travaillez dans une équipe Java ou C #, si le code actuel a été écrit par des développeurs expérimentés, il est facile pour moi de choisir le style de code et de le suivre. Si je ne le souhaite pas, je ne suis peut-être pas la bonne personne pour le poste. S'il n'y a pas de révision de code ni de programmation par paire pour me récupérer quand je ne respecte pas le style, la société a problème plus important que la façon dont je nomme les champs membres!

Java et C #, ainsi que la plupart des langages modernes, ont été définis de sorte qu’il existe peu de pièges "simples" dans lesquels un programmeur puisse tomber.

Cependant, lorsque j'ai commencé à programmer, j'utilisais le C (et plus tard le C ++). En C, vous pouvez écrire du code comme

if (a = 3);
{
   /* spend a long time debugging this */
}

Le compilateur ne générera pas d'erreur, ce qui est difficile à repérer lors de la lecture de beaucoup de code. Cependant, si vous écrivez:

if (3 = a)
{
   /* looks odd, but makes sense */
}

Le compilateur donne une erreur et il est facile de changer le code en 3 == a. De même, si la norme de codage ne permet pas =d’être utilisée dans une ifcondition ou une " ifinstruction vide ", un vérificateur de code peut être utilisé dans le cadre du système de construction pour suivre cette erreur.

Mon point de vue sur les normes de codage a beaucoup changé lorsque je me suis éloigné du C / C ++: j’aimais les normes de codage qui étaient appliquées de manière stricte et qui comportaient de nombreuses pages. Je pense maintenant qu'il suffit de répertorier les outils utilisés et d'obtenir un accord informel entre les membres de l'équipe d'origine sur quelques conventions de dénomination. Nous ne vivons plus dans un monde d'équipes de plus de 30 développeurs écrivant des applications en C / C ++ ...

Il y a une raison pour laquelle je n'ai jamais aimé JScript et je pense que TypeScript est la meilleure chose à faire pour le développement Web depuis des années. Je m'attends à ce que les développeurs d'interface Web aient toujours besoin de normes de codage en raison des défauts de conception de HTML / CSS / JScript, etc.

Avoir la source comme norme de codage auto-documentée implique deux choses.

1. Les personnes doivent consulter la base de code et la réviser afin de devenir des contributeurs compétents. C'est incroyablement important. Lire les directives de codage est une perte de temps par rapport à plonger dans la base de code.
2. Il concède que les différences mineures sont sans importance. Il est important de s’entendre sur les principes de base et de les comprendre. Le maintien d'un style cohérent n'est pas poursuivi comme l'art pour l'art. Il ne permet pas aux nitpickers non créatifs d'ennuyer et de distraire les autres. Il s'agit de faciliter la communication par le code en équipe.

Un document de normes de code fréquemment mis à jour et bien écrit peut être très utile, mais ce n'est généralement pas le cas. Le document de normalisation ne reflète pas les normes de codage réellement utilisées par la société, car il est très difficile de créer un bon document de normalisation et encore plus difficile de le tenir à jour.

Au lieu d'avoir un document de normes de codage médiocre et trompeur, il est préférable de n'en avoir aucun et de laisser le code lui-même représenter ces normes. Quoi qu’il en soit, le plus important est d’appliquer les normes du code, ce qui nécessite bien plus qu’un simple document. La motivation, les processus, les formations, les outils, etc. sont beaucoup plus importants.

Une chose très importante qui n’a pas été suffisamment clairement définie est que les normes de codage sont comme la langue: elles évoluent. Une norme de codage écrite est un obstacle, sinon, elle est continuellement obsolète et inutile.

Ne pas avoir une norme de codage clouée n'est pas si mal. Si vous effectuez des examens par les pairs lors de l'enregistrement, chaque fois que quelque chose non conforme à la norme de codage entre dans le référentiel, cela signifie que 2 personnes y ont réfléchi * et ont décidé que l'avantage de cette variation l'emportait sur l'incohérence avec le reste du code.

Le fait de ne pas avoir de norme écrite supprime également les formalités administratives qui empêcheraient une équipe d’une entreprise d’essayer une nouvelle version de la norme de codage pour un nouveau projet, soit parce qu’elles veulent essayer quelque chose, soit peut-être parce qu’une norme différente a des applications pratiques. sur certains des outils automatisés qu’ils utilisent.

Ecrire une norme a tendance à supprimer plus de flexibilité que prévu à l'origine, tout en prenant un temps considérable qui pourrait être consacré à d'autres tâches. Je ne dis pas que vous ne devriez jamais écrire de normes de codage, les normes écrites ont certainement leurs avantages, en particulier si des équipes travaillant dans des endroits différents travaillent sur la même base de code.

Fortement lié: évolution des normes de codage, comment les gérez-vous?

* Si les gens ne réfléchissent pas pendant que leurs pairs examinent le code à l'enregistrement, vos problèmes vont bien au-delà des normes de codage.

Les changer devient un obstacle majeur, et les gens adhéreront en toute sécurité à la lettre de la loi plutôt que d’engager leurs cerveaux et de faire ce qui est bien.

Il viendra un jour où une partie de la norme sera inutile et aggravera le code. Certaines personnes adhéreront à la norme, car elle est écrite et sécurisée, et parce que les règles doivent être respectées. Les personnes qui veulent écrire du bon code plutôt que du code conforme à la norme seront frustrées et en colère. Il y aura des arguments et des désaccords, alors que si la norme n'était pas écrite, il y aurait une exploration et une discussion.

Je pense que de nombreux articles ici confondent norme de codage avec guide de style .

S'assurer que les modules développés par différentes équipes ont les mêmes options de compilateur et qu'ABI est différent du nombre d'espaces mis en retrait.

Des éléments comme la bonne manière de structurer les fichiers #include et de ne pas polluer l'espace de noms global dans un fichier d'en-tête doivent être documentés afin qu'ils puissent être utilisés comme liste de contrôle lors du codage initial et de la révision du code.

En particulier, "n'utilisez pas XXX, car cela entraîne des problèmes de compatibilité avec YYY", ne serait pas ce que vous verriez par exemple si vous suivez un autre code, car il n'est pas là. Alors, que le code soit la manière dont les normes sont capturées peut ne pas être clair ou totalement absent pour certains types de normes, et donc cela ne peut pas être un plan universel.

Quelque chose de grave, qui est omniprésent et important, comme ne pas utiliser d'exceptions ou ne pas utiliser newdans certains systèmes intégrés, ne peut pas être simplement considéré comme un savoir culturel commun, car cette "information est culturelle (seulement)" est en contradiction avec les principes fondamentaux des normes de fabrication telles que développeur de ces systèmes embarqués utilise (par exemple pour les applications automobiles). Ces choses importantes doivent être documentées, validées et classées de manière formelle.

Mais cela s’applique au codage , pas au style .

Les inventeurs de C et C ++ montrent, par exemple, l’utilisation de noms en minuscules et non de CaMelCaSe. Alors pourquoi tant de développeurs ne suivent-ils pas l'exemple implicite de la source? Le style de la bibliothèque standard et du matériel didactique canonique ne devrait-il pas être le style implicite à suivre?

Pendant ce temps, les gens font suivre l'exemple des en- têtes de la bibliothèque standard pour des choses qui ne doivent pas être copiées, comme l'utilisation des __Uglynoms des paramètres macro et le fichier à inclure motif non répétition.

Donc, avoir des choses n'est souvent pas considéré comme un style important, ou inversement, avoir des exemples peut ne pas être clair quant à ce qui ne devrait pas être suivi dans le code de projet. Les deux sont des contre-exemples à la thèse selon laquelle il est préférable de laisser implicitement le "style" (ou les conventions de codage).