Pourquoi l'oncle Bob suggère-t-il que les normes de codage ne soient pas écrites si vous pouvez l'éviter?
Pendant que j'étais en lisant cette question , la réponse la plus votée citait Oncle Bob sur les normes de codage , mais j'étais confus par cette astuce:
- Ne les écrivez pas si vous pouvez l'éviter. Laissez plutôt le code être la façon dont les normes sont capturées.
Cela a rebondi dans mon cerveau, mais je n'ai pas pu trouver d'endroit où rester. Si une nouvelle personne se joint à l'équipe ou si les normes de codage changent, ne pourrait-il pas y avoir confusion d'informations?
Pourquoi ne devrais-je pas écrire une norme de codage?
Il y a quelques raisons.
- Personne ne lit la documentation.
- Personne ne suit la documentation même si elle la lit.
- Personne ne met à jour la documentation même s'il la lit et la suit.
- La rédaction d'une liste de pratiques est beaucoup moins efficace que la création d'une culture.
Les normes de codage ne portent pas sur ce que les gens devraient faire, mais sur ce qu'ils en fait font. Lorsque les gens s'écartent des normes, cela devrait être repris et modifié par le biais d'un processus de révision du code et/ou d'outils automatisés.
N'oubliez pas que le but des normes de codage est de nous faciliter la vie. Ils sont un raccourci pour notre cerveau afin que nous puissions filtrer les éléments nécessaires des éléments importants. Il est préférable de créer une culture de la révision pour faire respecter cela 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 considéré.
Ne capturez pas les normes de codage dans un document. Capturez-le dans le code, en ayant un processus automatisé qui vérifie que les normes sont respectées.
Ne vous fiez pas aux personnes qui référencent un document, mais en même temps, ne vous fiez pas aux personnes qui interprètent le code qui existe déjà et identifient ce qui est convention et ce qui est une coïncidence.
Incorporez quelque chose comme Checkstyle dans votre build de validation. Cela peut appliquer les règles de base telles que les normes de formatage et de dénomination, puis plutôt que de déployer des efforts mentaux en considérant le style, qui peuvent tous être déchargés dans un processus stupide qui est au moins garanti d'être approfondi.
Si c'est important, définissez strictement ce que vous voulez et échouez si c'est faux.
Les gens négligent le véritable objectif d'un document sur les normes de codage, qui est de régler les 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 la langue, et les concepteurs de langues commencent à réaliser que cela devrait faire partie de la spécification (par exemple, Go).
Parce qu'ils sont si insignifiants, les arguments peuvent devenir vraiment passionnants et durer sans fin, nuisant ainsi à la productivité et à la cohésion de l'équipe. Ou peut obscurcir votre historique des changements avec un reformatage sans fin entre deux ou plusieurs styles préférés de personnes.
Le fait d'avoir une norme écrite met fin à l'argument. Les gestionnaires peuvent pointer du doigt et dévier l'insatisfaction vers le document. Vous pouvez discuter avec un morceau de papier mais ça ne va pas vous écouter.
(Voir aussi La tyrannie de l'absence de structure )
Parce que les commentaires sont des mensonges .
La norme de codage est un très gros commentaire sur ce que devrait être le code. Le code lui-même est la source ultime de vérité. La vérité dans ce cas n'est pas le comportement du code, c'est le style dans lequel il s'exprime. Si vos normes ne sont pas déjà reflétées dans votre code, vous avez beaucoup de travail devant vous.
L'oncle Bob voit un commentaire comme un échec personnel du programmeur, car il prouve qu'il n'a pas réussi à exprimer le but du fragment de code avec le langage de programmation lui-même. De même, un document de normes est un échec à exprimer un style cohérent dans la base de code.
Les nouveaux programmeurs devraient passer du temps à regarder le code, et non passer des jours à lire un document de normes à plusieurs chapitres (j'ai dû le faire, soupir).
Un document de normes n'est pas une si mauvaise idée, mais j'ai été dans des ateliers de programmation où la maintenance des documents de normes était le travail à plein temps de quelqu'un. S'il vous plaît, si vous devez conserver un document de normes, gardez-le sur une page. Mais si vous avez déjà du code, est-ce que personne ne devrait pouvoir assembler le même document en moins d'une journée?
Il est important d'avoir des normes de code. Avoir un document qui dicte ce qu'ils ne sont pas.
Pourquoi l'oncle Bob suggère-t-il que les normes de codage ne soient pas écrites si vous pouvez l'éviter?
Si vous demandez des raisons derrière son opinion, vous pouvez avoir une réponse uniquement si il publiera une réponse ici ( notre opinion est tout simplement hors de propos), cependant .. .
Pourquoi ne devrais-je pas écrire une norme de codage?
Si vous demandez s'il est à droite à ce sujet: permettez-moi d'être le seul impopulaire (jusqu'à présent) à dire que vous n'avez aucune raison de l'éviter.
ÉCRIVEZ-LE . Cependant je vais essayer d'expliquer mes raisons ...
David a suggéré dans un commentaire que le point principal de la réponse de Stephen n'est pas pourquoi vous ne devriez pas - écrire les documents mais sous quelle forme ils sont. Si les directives sont formalisées dans tools (pas simplement une révision manuelle du code) alors je peux être d'accord (quand la loi n'exige pas autre chose). 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 package ou autre votre langue préférée appelle un limite.
Cependant, le libellé de l'oncle Bob ne me fait pas penser qu'il en parle.
Puis-je être en désaccord avec un tel expert senior? Je le fais, pour presque tous les points de l'article cité (voir également 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 directives de codage ne concernent pas seulement un formatage mineur problèmes).
- Dans certaines circonstances, des normes de codage écrites sont requises par la loi.
- Je lis de la documentation et je suis sûr que je ne suis pas seul. Les membres de l'équipe peuvent changer au fil du temps, les connaissances ne peuvent pas être dans une base de code vieille de 5 à 10 ans ou 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 elles vous intéressent. Si les normes ont changé, alors votre documentation (dans le code) est obsolète car tout votre code ne suit pas la nouvelle norme. Le reformatage/refactoring peut être lent mais vous avez toujours une directive écrite faisant autorité à suivre.
- Il vaut mieux lire un document de 5 pages que d'inspecter le LOC 10/20 K pour extrapoler une règle (que vous pouvez mal comprendre, BTW), cela ne fait aucun doute.
- Il est ironique que quelqu'un qui a écrit de nombreux livres sur les principes de conception et le style de codage suggère que vous ne devriez pas écrire vos propres directives, n'est-il pas préférable de nous jeter des exemples de code? Non, car les directives écrites vous disent non seulement quoi faire, mais aussi deux autres choses qui manquent au code: ce qu'il ne faut pas faire et les raisons de le faire ou non.
La "programmation auto-organisée gratuite" est bonne pour un gars ninja de 16 ans mais les organisations ont d'autres exigences :
- La qualité du code doit être accordée (et définie) au niveau de l'entreprise - ce n'est pas quelque chose qu'une seule équipe peut décider. Ils peuvent même ne pas avoir les compétences nécessaires pour décider de ce qui est mieux (combien de développeurs, par exemple, ont toutes les compétences requises pour examiner MISRA ou même simplement comprendre chaque règle?)
- Les membres peuvent être déplacés entre différentes équipes: si tout le monde suit les mêmes normes de codage, l'intégration est fluide et moins sujette aux erreurs.
- Si une équipe s'auto-organise, les normes évolueront avec le temps lorsque les membres de l'équipe changeront - vous aurez alors une énorme base de code qui ne suit pas les normes acceptées actuelles.
Si vous pensez à les gens avant le processus alors je ne peux que suggérer de lire sur TPS: les êtres humains sont une partie centrale du Lean mais les procédures sont très formalisées.
Bien sûr, une petite organisation avec une seule équipe - mai laisser l'équipe décider des normes à adopter, mais cela doit être écrit. Ici sur Programmers.SE, vous pouvez lire les articles d'Eric Lippert: Je suppose que nous sommes tous d'accord pour dire qu'il est un développeur expérimenté, quand il a travaillé pour Microsoft, il a dû se conformer à leurs directives écrites (même si certaines règles peuvent être incorrectes, sans objet ou inutile pour lui.) Et Jon Skeet? Les directives de Google sont assez strictes (et beaucoup de gens ne sont pas d'accord avec elles) mais il doit se conformer à ces directives. Est-ce irrespectueux envers eux? Non, ils ont probablement travaillé pour définir et améliorer de telles directives, une entreprise n'est pas faite par un membre (ou une équipe) et chaque équipe n'est pas une île .
Exemples
- Vous avez décidé de ne pas utiliser l'héritage multiple et les classes imbriquées en C++ parce que vous, les membres réels de l'équipe ne le comprenez pas bien. Plus tard, quelqu'un qui souhaite utiliser l'héritage multiple 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 alors, s'il n'a pas été utilisé, est-ce parce qu'il est contraire à la norme de codage ou est-il autorisé, mais il n'y avait tout simplement pas de situations antérieures où l'héritage multiple était un bon choix?
- 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 les 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 incorrects et vous commencez à éviter de les utiliser. Quelle est la règle que votre code vous dit? C'est mauvais parce que standard évolue mais la base de code est plus lente à évoluer et si c'est votre documentation alors vous avez des ennuis.
- Jon est passé de l'équipe A à l'équipe B. Jon doit apprendre une nouvelle norme; tout en apprenant, il introduira probablement des bogues plus subtils (ou, s'il est chanceux, prendra juste beaucoup de temps pour comprendre le code existant et allonger la révision du code).
- L'équipe A passe à une base de code appartenant auparavant à 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.
Vrai, jusqu'à ce que vous n'ayez pas de standard et que votre organisation vous ait assigné la tâche à build one.
Qu'ils soient spécifiques à l'équipe plutôt qu'à l'entreprise.
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 toujours la mémoire de guerres sans fin (et inutiles) sur le formatage. Je ne veux pas les vivre encore et encore, définissez-le une fois pour toutes.
Ne les écrivez pas si vous pouvez l'éviter. Laissez plutôt le code être la façon dont les normes sont capturées.
Non, pour toutes les raisons expliquées ci-dessus (bien sûr, sauf si vous refactorisez tout votre code en une seule fois lorsque les directives changent). Voulez-vous laisser votre code tel quel? Comment inspectez-vous la base de code pour comprendre les directives actuelles? Recherche par fichier age et adaptation de votre style de codage à l'âge du fichier source?
Ne légiférez pas sur une bonne conception. (par exemple, ne dites pas aux gens de ne pas utiliser goto)
Certes, les lignes directrices doivent être courtes ou personne ne les lira. Ne répétez pas l'évidence.
Assurez-vous que tout le monde sait que la norme concerne la communication et rien d'autre.
Non seulement, un bon standard concerne environ qualité sauf si vous voulez avoir un standard uniquement mineur détails.
Après les premières itérations, rassemblez l'équipe pour décider.
Voir le premier point et n'oubliez pas qu'une norme de codage est généralement un processus qui a pris de nombreuses années à être développé et affiné: quelques itérations, peut-être avec des développeurs juniors? Vraiment? Voulez-vous compter sur 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++ un standard au niveau de l'entreprise est encore plus nécessaire qu'en Java.
- Ce raisonnement mai ne s'applique pas entièrement (et les raisons de l'oncle Bob peuvent être moins extrême) si vous travaillez dans une très petite entreprise où vous n'avez qu'une petite équipe.
- Vous êtes embauché (en équipe) et vous travaillerez seul avec un nouveau projet puis vous l'oublierez et passerez à autre chose. Dans ce cas vous peut ne pas s'en soucier (mais votre employeur devrait ...)
- Pour être utile, une norme de codage ne doit pas parler de questions de fond; seulement des questions de style. Il ne doit spécifier que les éléments arbitraires et ambigus. par exemple. Placement des accolades, profondeur d'indentation, espaces vs tabulations, conventions de dénomination, etc.
- Les problèmes de style sont locaux et non mondiaux. Chaque équipe doit adopter son propre style particulier, adapté à sa tâche et à sa personnalité. Cela maintient les normes simples et légères. Les normes d'entreprise deviennent surchargées de toutes les considérations, configurations et exceptions possibles.
- 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 répond pas à la norme. Dans ce cas, vous n'avez pas de norme. Pour être efficace, la norme doit ê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 distinct.
- Dans les systèmes hérités, les équipes et les styles changent avec le temps. Il n'y a rien de mal à cela. L'ancien code aura un style plus ancien. Un code plus récent aura un style plus récent. L'équipe doit être consciente des styles et de leur âge. Chaque fois qu'un nouveau code est écrit, il doit être dans le nouveau style, peu importe où dans le code il se trouve.
Pourquoi ne devrais-je pas écrire une norme de codage?
Il y a plusieurs raisons à cela. Voici quelques considérations:
Combien de temps les gens passent-ils à "apprendre" les normes de code pour avoir beaucoup de temps à consacrer à toute l'équipe à réviser, discuter, documenter, réviser ... etc. les normes de code. C'est comme discuter constamment de votre "Manuel de l'employé" - à quelle fréquence cela figure-t-il à l'ordre du jour d'une réunion d'équipe?
Lorsqu'un projet est financé/abandonné/etc. alors les quelques personnes qui restent habituellement ne peuvent pas continuer à adhérer (ou peut-être même ne pas avoir lu) les normes. La prochaine chose que vous savez, tous ces efforts pour "garder le code propre" ont été gaspillés de toute façon.
Si le projet s'arrête ou qu'une nouvelle piste est introduite, il est très probable que la personne ignorera totalement les règles précédentes et voudra le faire d'une nouvelle manière. Encore une fois, qu'est-ce qui a été gagné en codifiant les normes ??
Vous devriez être sûr de lire # 6:
Après les premières itérations, rassemblez l'équipe pour décider.
En d'autres termes, quand il est temps de démarrer un projet, suivez le flux pendant un certain temps. Ensuite, discutez des règles générales des normes de codage que l'équipe actuelle utilise - et suivez-les. De cette façon, vous maximisez l'effort nécessaire pour améliorer le produit tout en minimisant l'effort nécessaire pour écrire, réviser et documenter le "sucre syntaxique" qui a été nécessaire 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 grandement des règles exactes sur l'espacement, les nouvelles lignes, etc. mais vous pouvez éviter constamment ennuyeux développeurs en ayant au moins quelques règles.
Une autre réponse qui, à mon avis, n'a pas été énoncée assez clairement, est que cela signifie également que les gens ne suivent pas les règles aveuglément. Cela signifie que les gens doivent trouver justifications réelles de leurs décisions de conception et conventions de codage plutôt que de simplement dépendre du fait qu'il a été écrit pour le justifier.
Tout d'abord, pour autant que je sache, l'oncle Bob est un Java personne, 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 codage et de le suivre. Si Je ne suis pas disposé à le faire, peut-être que je n'étais pas la bonne personne pour le travail ... S'il n'y a pas de révision de code ou de programmation par paire pour me prendre quand je ne respecte pas le style, alors l'entreprise a un problème plus important que la façon dont je nomme les champs membres!
Les deux Java et C #, ainsi que la plupart des langages modernes, ont été définis de sorte qu'il y ait peu de pièges "simples" pour un programmeur.
Cependant, lorsque j'ai commencé à programmer, j'utilisais C (et plus tard C++). En C, vous pouvez écrire du code comme
if (a = 3);
{
/* spend a long time debugging this */
}
Le compilateur ne donnera pas d'erreur, et c'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 = à utiliser dans une condition if ou une "instruction if vide", un vérificateur de code peut être utilisé dans le cadre du système de génération pour suivre cette erreur.
Mon point de vue sur les normes de codage a considérablement changé lorsque je me suis éloigné de C/C++: j'aimais les normes de codage strictement appliquées et de nombreuses pages. Je pense maintenant qu'il vous 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 qui puisse arriver au développement web depuis des années. Je m'attends à ce que les développeurs de l'interface utilisateur Web aient encore besoin de normes de codage en raison des défauts de conception de HTML/CSS/JScript, etc.
Le fait que la source soit la norme de codage auto-documentée implique deux choses.
- Les gens doivent consulter la base de code et la réviser afin de devenir des contributeurs compétents. C'est extrêmement important. La lecture des directives de codage est une perte de temps par rapport à la plongée dans la base de code.
- Il admet que les différences mineures sont sans importance. Il est important de s'entendre et de comprendre les principes de base. Le maintien d'un style cohérent n'est pas poursuivi comme l'art pour l'art. Il ne permet pas aux piqueurs de crêpes peu créatifs de déranger et de distraire les autres. Il s'agit de faciliter la communication via le code au sein d'une é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 normes ne reflète pas les normes de codage réelles utilisées par l'entreprise car il est très difficile de créer un bon document de normes et encore plus difficile de le maintenir à jour.
Au lieu d'avoir un document de normes de codage médiocre et trompeur, il vaut mieux n'en avoir aucun et laisser le code lui-même représenter ces normes. Quoi qu'il en soit, la partie la plus importante consiste à 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 énoncée est que les normes de codage sont comme le langage: elles évoluent. Une norme de codage écrite fait obstacle à cela, et si ce n'est pas le cas, elle est continuellement obsolète et inutile.
Ne pas avoir de norme de codage clouée n'est pas si mal. Si vous effectuez des évaluations par les pairs à l'enregistrement, chaque fois qu'un élément non conforme à la norme de codage entre dans le référentiel, cela signifie que 2 personnes y ont pensé * et ont décidé que l'avantage de cette variation l'emportait sur l'incohérence avec le reste du code.
Ne pas avoir de norme écrite supprime également les formalités administratives qui empêcheraient une équipe d'une entreprise d'essayer une nouvelle variante de la norme de codage pour un nouveau projet, soit parce qu'elle veut essayer quelque chose, soit parce qu'une autre norme a des applications pratiques. sur certains des outils automatisés qu'ils utilisent.
Rédaction d'une norme a tendance à supprimer plus de flexibilité que prévu à l'origine, tout en occupant un peu de temps qui pourrait être consacré à d'autres choses. Je ne dis pas que vous ne devriez jamais écrire des normes de codage, les normes écrites ont certainement leurs avantages, surtout si les équipes travaillant dans des endroits différents travaillent sur la même base de code.
Fortement lié: Evolution des normes de codage, comment les traitez-vous?
* Si les gens ne pensent pas lors de l'examen par les pairs du code lors de l'enregistrement, vos problèmes sont bien plus importants que les 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 le cerveau et de faire la bonne chose.
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ûre, et parce que les règles doivent être respectées. Les gens qui veulent écrire du bon code plutôt que du code conforme aux normes seront frustrés 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 exploration et discussion.
Je pense que de nombreux messages ici prêtent à confusion standard 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 ABI est un type de chose différent du nombre d'espaces en retrait.
Des choses comme la bonne façon de structurer les fichiers #include et de ne pas polluer l'espace de noms global dans un fichier d'en-tête devrait être documentées afin qu'elles puissent être utilisées comme liste de contrôle lors du codage initial et des révisions de code.
En particulier, "n'utilisez pas XXX car cela provoque des problèmes de compatibilité avec YYY" n'est pas quelque chose que vous verriez par exemple en suivant un autre code, car ce n'est pas Là. Donc laissez le code être la façon dont les normes sont capturées peut être peu clair ou complètement absent pour certains types de normes, et donc cela ne peut pas être un plan universel.
Quelque chose de très répandu et important comme ne pas utiliser d'exceptions ou ne pas utiliser new dans certains systèmes embarqués ne peut pas être simplement laissé à la connaissance de la culture commune, car "l'information est culturelle (uniquement)" contredit les principes fondamentaux des normes de fabrication comme ISO-9000, que le développeur de ces systèmes embarqués utilise (par exemple pour les applications automobiles). Ces éléments importants doivent être documentés, signés et archivés 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 pas CaMelCaSe. Alors pourquoi tant de développeurs ne suivent-ils pas l'exemple implicite de la fontaine? Le style de la bibliothèque standard et du matériel pédagogique canonique ne devrait-il pas être le style implicite à suivre?
Pendant ce temps, les gens suivent l'exemple des en-têtes de bibliothèque standard pour les choses qui ne devraient pas être copiées, comme l'utilisation de __Ugly noms des paramètres de macro et du modèle de non-répétition du fichier d'inclusion.
Donc, avoir des choses n'est souvent pas considéré comme un style important, ou à l'inverse, avoir des exemples peut ne pas être clair quant à ce qui ne devrait pas être suivi dans le code du projet. Les deux sont des contre-exemples de la thèse selon laquelle il est préférable de laisser implicite le "style" (ou les conventions de codage).