L’importance de la charge cognitive

• Ce projet open source répertorie de manière structurée diverses méthodes et de nombreux exemples pour réduire la charge cognitive dans le développement logiciel
• Un code, une structure et des abstractions inutilement complexes nuisent à la productivité des développeurs et augmentent les coûts de maintenance
• Pour les modules, plutôt que des éléments « petits et superficiels », il est préférable d’avoir des structures profondes avec une interface simple et des fonctionnalités puissantes
• L’abstraction excessive, la dépendance aux frameworks et l’usage abusif du principe DRY sont au contraire des facteurs qui alourdissent la charge cognitive
• La meilleure architecture est une base de code simple, que même un nouveau développeur peut comprendre rapidement

---

Résumé du projet et intérêt

Cette ressource open source sur GitHub met l’accent sur la « charge cognitive » comme l’un des principes fondamentaux du développement logiciel. Sa principale particularité est d’organiser, au moyen de nombreux exemples et solutions, les sources de complexité que les développeurs rencontrent réellement, indépendamment de la taille de l’équipe ou des tendances technologiques. Contrairement à d’autres ressources centrées sur les bonnes pratiques, elle prend aussi en compte la charge psychologique et cognitive, ce qui en fait un atout concret pour la maintenance et l’onboarding de nouveaux membres de l’équipe.

Introduction

• Les concepts à la mode et les bonnes pratiques que l’on entend dans le développement échouent souvent en situation réelle
• La cause principale de la confusion ressentie sur le terrain, ainsi que des pertes de temps et de coûts qui en découlent, est une charge cognitive élevée
• Les développeurs passent plus de temps à lire et comprendre le code qu’à l’écrire
• Le texte se concentre sur des moyens pratiques de réduire la charge cognitive inutile (Extraneous Cognitive Load)

Qu’est-ce que la charge cognitive ?

• La charge cognitive désigne la quantité d’informations qu’un développeur doit garder en tête pour accomplir une tâche
• En moyenne, on ne peut conserver en mémoire à court terme qu’environ 4 « blocs d’information » à la fois (conditions, valeurs de variables, etc.)
• Quand la charge cognitive atteint un seuil critique, la compréhension et la vitesse de développement chutent fortement

Types de charge cognitive

• Charge cognitive intrinsèque (Intrinsic) : elle provient de la difficulté inhérente à la tâche elle-même. Elle ne peut pas être réduite
• Charge cognitive inutile (Extraneous) : elle provient d’une complexité artificielle, comme la manière de présenter l’information, la conception de la structure ou des patterns superflus. Elle peut être activement réduite

Exemples pratiques et pistes d’amélioration

Conditions complexes

• Un code avec plusieurs conditions imbriquées augmente la charge cognitive, car il faut mémoriser davantage d’éléments à chaque étape
• Solution : introduire des variables intermédiaires explicites afin de clarifier l’objectif de chaque condition

if imbriqués vs Early Return

• Par rapport aux if imbriqués, le pattern Early Return réduit la charge liée à la mémorisation des préconditions
• Il permet de ne retenir que le « happy path » et libère ainsi la mémoire de travail

Effets indésirables de l’héritage

• Une hiérarchie d’héritage profonde (par ex. ClasseA → ClasseB → ClasseC…) exige de retenir simultanément de nombreuses couches d’information pour comprendre le code, ce qui fait exploser la charge cognitive
• Solution : privilégier la composition, et utiliser l’assemblage plutôt que l’héritage inutile

Trop de modules/fonctions superficiels

• Plutôt que 80 classes petites et superficielles, il est plus facile à maintenir d’avoir quelques modules profonds dotés d’interfaces puissantes et simples
• L’exemple donné est l’interface simple des E/S UNIX (open, read, write, lseek, close)

Mauvaise compréhension généralisée du principe de responsabilité unique

• L’interprétation floue de « ne faire qu’une seule chose » produit au contraire une multitude d’abstractions superficielles et peu claires
• En pratique, il faut plutôt l’interpréter comme « être responsable vis-à-vis d’une seule partie prenante », afin de mieux comprendre la relation métier et de réduire la charge cognitive

Abus des microservices

• Trop de microservices superficiels obligent à garder en tête en permanence leurs relations et intégrations, ce qui augmente la charge cognitive ainsi que les coûts de débogage et de mise en production
• Au départ, une structure monolithique bien aboutie peut au contraire être plus avantageuse pour la maintenance

Trop de fonctionnalités/options dans le langage

• Les nombreuses nouvelles fonctionnalités d’un langage (notamment en C++) conduisent au contraire à suivre la trace du « pourquoi cette implémentation a été faite ainsi », ce qui accumule la charge mémorielle
• Cela multiplie une charge cognitive secondaire sans lien avec le métier

Mapping entre codes de statut HTTP et logique métier

• Le mapping arbitraire entre des codes de statut HTTP (401, 403, 418, etc.) et des significations métier internes oblige tous les membres de l’équipe à les mémoriser
• Amélioration : transmettre les informations de manière cohérente avec des codes textuels auto-explicatifs (par ex. "jwt_has_expired")

Usage abusif du principe DRY (Do not repeat yourself)

• Dans une base de code complexe, forcer la suppression des duplications crée de fortes dépendances et augmente au contraire la charge cognitive ainsi que le coût des changements
• Le texte cite la formule célèbre de Rob Pike selon laquelle, en local, « un peu de copie » peut être préférable

Dépendance aux frameworks et effets néfastes de la Layered Architecture

• Lorsqu’on dépend profondément de la structure « magique » d’un framework, un nouveau développeur met beaucoup de temps à comprendre la logique interne
• L’accumulation de couches d’abstraction fait exploser la charge cognitive au moment de remonter à la cause réelle d’un problème
• Il faut se concentrer sur les principes fondamentaux : Dependency Inversion, Information Hiding et contrôle de la charge cognitive

Mauvaise compréhension du Domain-Driven Design (DDD)

• Le cœur du DDD est l’analyse du domaine métier ; s’obséder sur la structure des dossiers ou sur des patterns peut au contraire provoquer des interprétations subjectives et de la charge cognitive
• Des frameworks comme Team Topologies sont plus efficaces pour répartir la charge cognitive

Familiarité vs simplicité

• La familiarité n’est pas la même chose que la simplicité. Si quelque chose semble léger, c’est parce qu’on y est habitué, pas parce que sa structure est réellement simple
• Si une nouvelle recrue reste confuse pendant plus de 40 minutes, c’est un signal qu’il faut améliorer le code

Cas réels de réussite et d’échec

• Comme Instagram, il est possible d’obtenir une forte montée en charge et une bonne maintenabilité avec une architecture monolithique simple
• Les entreprises où des « développeurs vraiment brillants » ont conçu des structures complexes ont au contraire souvent connu des échecs
• Une structure que tous les développeurs peuvent lire facilement et qui permet un onboarding rapide joue un rôle clé dans l’amélioration de la productivité

Conclusion

• La charge cognitive inutile, au-delà du travail intrinsèque, nuit à tous les acteurs du développement
• Le meilleur code est celui que d’autres développeurs à l’avenir, ainsi que soi-même, peuvent comprendre le plus rapidement possible
• À long terme, des solutions ordinaires et directes sont plus favorables à la maintenance et à la productivité d’équipe que des structures « qui ont l’air intelligentes »

Références / remarques

• Des avis de Rob Pike, Andrej Karpathy, Elon Musk, Addy Osmani, antirez (développeur de Redis) et d’autres développeurs connus sont également cités
• Le texte présente des enseignements cohérents avec des cas réels à grande échelle comme Chromium, Redis et Instagram
• La simplicité, la clarté et la réduction de la charge cognitive sont au cœur de la durabilité logicielle

Valeur de ce projet open source

• Une ressource centrée sur l’expérience réelle des développeurs et des cas pratiques, là où de nombreux livres de conception logicielle ou catalogues de patterns passent à côté de l’essentiel
• Une aide immédiate et concrète pour de nombreuses équipes, qu’il s’agisse d’onboarding, de revues d’architecture ou de maintenance à long terme
• Sert de checklist permettant de réexaminer le code à travers le prisme clair de la « charge cognitive »

[GN⁺]

Avis Hacker News

• J’ai eu mon plus grand déclic avec le livre A Philosophy Of Software Design de John Ousterhout ; c’est le meilleur livre sur ce sujet, et je le recommande absolument à tout développeur. L’idée centrale est que l’objectif de la conception logicielle doit être de minimiser la complexité, définie ici comme « à quel point il est difficile de modifier quelque chose », et cette « difficulté » est déterminée par la charge cognitive nécessaire pour comprendre le code.

  • Le problème, c’est qu’aucune règle ne remplacera jamais le jugement, l’expérience et l’intuition. Toute règle peut devenir un outil de dispute, et on ne gagne jamais un débat d’architecture. Si ce texte est bon, c’est parce que ceux qui n’en ont pas besoin le savent déjà, et que ceux qui en auraient vraiment besoin ne le comprendront pas. Au fond, ce n’est pas un problème technique, mais un problème de personnes et de culture. L’architecture découle finalement des personnes et de la culture. De la même façon qu’il a fallu Rob Pike et Google pour faire naître Go, on ne crée pas un langage comme Go juste en lisant un livre.

  • Je pense que le principe DRY (ne pas se répéter) n’est à envisager qu’après avoir suffisamment compris l’application et en avoir déjà construit plusieurs versions. Au début, il vaut mieux répéter pour comprendre d’abord l’espace du problème, puis réfléchir à la maintenabilité dans une deuxième version. Ce n’est qu’autour de la troisième version qu’on peut enfin appliquer DRY.

  • Il est incroyablement difficile d’obtenir ce livre sans donner d’argent à Jeff Bezos. Si quelqu’un connaît l’auteur John, j’aimerais vraiment qu’on lui signale ce problème. Il n’était pas disponible à la librairie du campus, ni dans les librairies locales, ni chez Powell’s.

  • J’ai renoncé depuis longtemps à chercher la solution logicielle parfaite. J’ai l’impression que personne n’a jamais tout mis parfaitement en ordre. Au final, nos meilleures armes restent la sagesse et l’expérience des gens. Les contextes, les secteurs et les équipes sont trop différents pour qu’on puisse tout définir proprement avec des chiffres ou des lois. Aujourd’hui, mon objectif en conception est de trouver l’équilibre entre le « bazar » et la « beauté ». Le plus difficile, c’est que le métier est incertain alors que le logiciel est déterministe : les exigences business changent sans cesse, et il est difficile de les faire entrer dans la rigidité d’un système informatique. Maintenant, je ne tente un refactoring que lorsque je ressens directement une gêne au moment de modifier le code. Et même là, je ne fais qu’un minimum de ménage. En répétant ce type de refactorings itératifs, de nouveaux patterns émergent, et on peut parfois en extraire des abstractions.

  • Ce livre est précisément la meilleure référence sur le sujet. Le texte en question s’en est inspiré. J’ai aussi échangé une ou deux fois avec John à propos de son contenu.

• La capacité à écrire du code qui réduit la charge cognitive des autres est une compétence très rare et très difficile. Même quand on l’a, cela demande un effort constant. En fin de compte, le travail du développeur consiste à compresser l’idée centrale pour n’en laisser apparaître que l’essentiel, et à n’exposer que la complexité strictement nécessaire. En pratique, j’ai rarement vu quelqu’un vraiment bien faire cela.

  • Un code vraiment bien conçu donne finalement aux gens l’illusion que « c’était donc un problème simple depuis le départ ? ». À l’inverse, un code visiblemement complexe, en « château de cartes », reçoit de la reconnaissance pour l’effort apparent qu’il représente, et cela peut même mener à des promotions.

  • C’est exactement la même chose pour les interfaces, l’UX et le design d’interaction. Les développeurs tolèrent bien mieux la charge cognitive que le grand public, mais créer quelque chose que des non-techniciens utiliseront facilement exige de sortir de sa propre intuition de développeur, ce qui est extrêmement difficile. Concevoir des outils permettant à des utilisateurs ordinaires de résoudre intuitivement des problèmes complexes est vraiment dur.

  • La plupart des abstractions ne survivent pas bien à un changement des exigences. Les frameworks que j’aime savent qu’on ne peut pas créer pour toujours une couche d’abstraction parfaite, et fournissent volontairement des « portes de sortie ». (Par exemple : donner une référence directe à un élément html dans un framework d’UI web.) La sagesse consiste à accepter qu’on ne peut pas prédire parfaitement l’avenir.

  • En pratique, ce genre de compétence est plus un bonus qu’un prérequis essentiel dans beaucoup d’entreprises. Il suffit de regarder les principaux codebases pour s’en rendre compte.

• Je me considère comme l’un de ces « développeurs brillants au tempérament un peu bizarre ». J’aime construire des abstractions. Je trouve à la fois fascinant et inquiétant que l’industrie semble aujourd’hui revenir à une « architecture en tas de if ». Je comprends pourquoi beaucoup aiment ça : ça paraît simple, c’est facile à comprendre, et il suffit de fermer les tickets assignés. La plupart des processus de développement reposent sur des tas de if, et cette approche fonctionne réellement assez bien au-delà d’un certain volume de cas. Même quand il y a une fuite massive de données personnelles, il n’y a pas forcément grand monde pour en répondre. Mais le vrai problème, c’est que je ne sais pas s’il existe une meilleure alternative. Les abstractions sophistiquées et les belles architectures ne semblent pas vraiment améliorer la cohérence réelle du code. Surtout en environnement d’entreprise, où les propriétaires de la logique métier prêtent très peu d’attention à cette logique, il est impossible de construire prudemment de jolies abstractions. Au final, on a une exigence du type « les commandes ne sont livrées qu’à une seule adresse », puis soudain « un gros client veut être livré à plusieurs adresses », et dans ce chaos il devient difficile d’imaginer une abstraction sans bug. J’en viens parfois à me demander si, de façon réaliste, le « tas de if » n’est pas la meilleure solution en logiciel d’entreprise.

  • À la question « le tas de if est-il vraiment la meilleure approche ? », je recommande l’article Big Ball of Mud et ce résumé. Les systèmes réels évoluent toujours : ils commencent souvent comme un « tas de boue », puis on améliore certaines parties, avant que de nouveaux changements ne viennent de nouveau faire s’effondrer les belles abstractions. L’essentiel est de faire croître le système comme une petite ville qui devient une métropole, grâce à un mélange de modélisation du domaine, d’abstractions raisonnables et de changements destructeurs quand ils sont nécessaires.

  • On peut créer de belles abstractions même dans ce genre de logiciels, mais dès que la logique métier s’en mêle, elles deviennent difficiles à maintenir. Les abstractions qui tiennent le mieux concernent surtout des éléments produits ou techniques, comme l’authentification, les permissions, les logs, la base de données, le middleware ou l’infrastructure. Dès que la logique interne du métier commence à influencer l’abstraction, tout redevient chaotique. Dans certains endroits, on a même laissé les équipes métier gérer elles-mêmes la logique ; c’est devenu impossible à tester, incompréhensible, et même impossible à simuler. Il faut alors des opérateurs, et on se retrouve avec des développeurs juniors qui « codent » via des outils graphiques. Même après plusieurs réécritures, au bout de 2 ou 3 ans, tout redevient toujours désordonné.

  • Il est absolument impossible pour les équipes métier d’expliquer parfaitement leur logique à ceux qui l’implémentent. Même si elles la comprennent elles-mêmes, elles ne savent pas l’exprimer du point de vue du code. En pratique, il faut qu’au moins un implémenteur vive réellement l’expérience utilisateur jusque dans ses tripes pour bien comprendre. Or, les entreprises imposent la séparation des services, et la « logique métier » devient alors une zone dont personne ne se soucie vraiment, qu’on finit par manipuler uniquement avec des if.

  • Le point essentiel, c’est que la réalité, c’est-à-dire le business lui-même, est déjà un énorme tas de if. Si le problème ou le domaine est clairement technique ou généralisable, on peut réduire les if grâce à l’abstraction ; mais si le domaine lui-même est chaotique, alors l’abstraction ne peut qu’intégrer la « flexibilité » comme propriété de base. La contradiction peut même devenir une fonctionnalité.

  • Si on joue avec des outils comme Codex CLI, on voit que lorsqu’ils rencontrent un bug, ils produisent systématiquement un patch en if pour ce cas précis. À moins de leur enseigner explicitement un pattern et de leur demander une nouvelle abstraction, ils continueront à ajouter des if qu’ils appellent des « heuristiques ». Dix bugs d’un certain type produiront dix patchs, et au onzième bug similaire, cela cessera évidemment de fonctionner. La solution proposée par Codex n’est qu’un empilement de répétitions de if.

• Je me demande à quel point il est fréquent, dans la vraie vie, qu’on vous demande de modifier un projet que vous ne connaissez absolument pas. À moins de changer très souvent de projet, cela arrive peut-être une fois tous les deux ans. Je pense qu’il vaut mieux se concentrer sur les vrais problèmes difficiles plutôt que sur le manque d’expérience.

• J’ai travaillé 8 ans dans l’organisation des développeurs chez Microsoft, et au début la modélisation des types d’ingénieurs était très utile. Il y avait trois personas, remplacés plus tard par un framework plus complexe. Malgré cela, les personas d’origine m’ont énormément aidé tout au long de ma carrière à communiquer efficacement avec d’autres ingénieurs.

  • Mort : l’ingénieur pragmatique ; le résultat business passe avant tout. Même un tas de if suffit si ça marche vite.
  • Elvis : l’innovation avant tout ; il veut utiliser les dernières technologies et que son génie soit reconnu. Obsédé par l’introduction de nouveaux frameworks, le code instable, la visibilité et l’innovation.
  • Einstein : obsédé par la performance, l’élégance et la rigueur technique. Il accorde plus d’importance à la cohérence du code et à sa qualité technique. En réalité, tous les ingénieurs sont un mélange de ces trois profils. Après quelques PR et revues de conception, on peut généralement repérer la tendance dominante.

  • Je pense qu’il faudrait y ajouter un type d’ingénieur nommé Amanda. Après 20 ans passés à relire son propre code chaotique et celui des autres, elle a intégré que le code est avant tout destiné à être lu par des humains. J’aimerais constituer une équipe uniquement avec des Amanda.

  • Mort est le pragmatique, Einstein le perfectionniste, et Elvis… est en fait plutôt nuisible au projet. C’est un peu motivant, mais l’équipe idéale combine bien Mort et Einstein. Il faut faire quelque chose d’aussi simple que nécessaire, tout en étant assez correct pour que la maintenance ne devienne pas pénible. D’ailleurs, si on confie un projet de long terme à un Mort, il finit souvent par commencer à se soucier des choses comme un Einstein. Petite parenthèse : les agents de codage automatiques récents ont un profil beaucoup trop Mort, au point que je dois maintenant moi-même les gérer comme un Mort.

  • Les personas sont de bons outils. D’après mon expérience, ils finissent avec le temps par se dégrader en mauvais raccourcis. Elvis était en réalité un terme de politique interne et, comme avec la loi de Goodhart, tout le monde a fini par l’utiliser en débat parce que cela avait l’air logique, ce qui a réduit son utilité. Alan Cooper avait introduit le concept de persona à l’époque de Visual Basic. Il est important de comprendre qu’une personne comme moi et, par exemple, un scientifique ou un développeur firmware n’ont pas les mêmes valeurs. Livre associé

  • Je pense que les meilleurs ingénieurs sont ceux qui savent ajuster ces trois tendances en fonction du projet, du contexte et de leurs objectifs personnels. Le dosage nécessaire dépend du rôle. Par exemple, pour l’optimisation d’un compilateur, on a davantage besoin d’Einstein et de Mort, tandis que pour du code de moteur de jeu, la répartition est différente. On peut débattre de l’exactitude de chaque trait, mais l’essentiel est que tout le monde doit fonctionner différemment selon les moments.

  • Je pense qu’il faut des garde-fous à cette approche. Réduire les gens à des catégories trop simples peut être injuste et devenir une étiquette permanente. D’après mon expérience, les dirigeants préfèrent souvent Mort à Elvis. En réalité, la solution réside dans le leadership et le management. Si on inclut des critères de qualité du code dans les exigences données à Mort, il peut produire de bonnes choses, même un peu plus lentement. Elvis a besoin de limites, et pour les Einstein il faut fixer clairement des contraintes pratiques et des échéances. Cette méthode a ses limites, car elle ignore la complexité humaine.

• Je crains que l’IA nuise à l’industrie du logiciel. L’IA n’a pas les limites humaines, donc elle peut écrire du code extrêmement complexe, difficile à lire, mais fonctionnel ; puis, quand tout finira par casser, plus personne ne saura le réparer. C’est pourquoi je conseille aux ingénieurs juniors de ne pas dépendre uniquement de l’IA et d’apprendre les caractéristiques du codebase. Sinon, ils perdront la capacité d’écrire eux-mêmes du code.

  • Je ne trouve pas cet argument convaincant, puisqu’on peut demander à l’IA de réparer à nouveau quand cela cesse de fonctionner.

  • Pour ma part, j’exige toujours que l’IA simplifie son code jusqu’à ce que je puisse le comprendre. Si l’approche est trop compliquée, je lui demande une version plus simple ; si elle utilise des bibliothèques externes inutiles, je lui demande de les retirer et de se limiter à la stdlib ou aux dépendances déjà présentes. L’IA écrit du code à ma place, pas pour elle-même.

  • Au contraire, je pense que l’IA pourrait améliorer la qualité logicielle en réduisant la charge cognitive liée à la conception bas niveau, ce qui nous permettrait de nous concentrer davantage sur l’architecture globale.

• À propos de la « manie propre aux développeurs brillants » mentionnée dans l’article, on dirait que l’auteur veut dire qu’il ne comprend que le code qu’il a lui-même écrit, ou du code écrit dans son style. Pourtant, le vrai secret pour réduire la charge cognitive consiste à minimiser la quantité de code qu’on n’a pas besoin de lire. Des frontières solides et des API claires rendent les changements plus faciles ; l’essentiel n’est pas de s’occuper de tout le code, mais uniquement de la complexité dérivée d’interfaces bien définies. La singularité du « développeur brillant » n’est au fond qu’un problème superficiel.

  • C’est justement le plus grand avantage du concept de microservices. Si deux équipes ne communiquent qu’au travers d’une API, et que des outils comme les schémas définissent strictement les frontières, alors on devient extrêmement conservateur sur les changements et on réfléchit beaucoup plus en amont. J’y vois une façon d’insérer techniquement une friction artificielle aux endroits qu’on ne veut surtout pas voir bouger.

  • En déboguant, j’ai souvent ressenti à quel point il est fatigant d’avoir des parties de code sur-optimisées pour le debugging direct dans la call stack. C’est pourquoi, quand on extrait certaines parties dans des fonctions séparées et qu’on découpe les commits, il devient plus facile de rollback des modifications non souhaitées, et la concentration sur le code s’améliore. Tout remontera peut-être dans une même PR, mais même ainsi, des frontières claires changent énormément les choses.

  • Les développeurs ont généralement du mal à penser en termes de « contrat et interface ». Il faut qu’ils regardent uniquement les promesses visibles de l’extérieur, pas l’implémentation interne. L’objectif est de pouvoir comprendre sans lire le code. Si quelqu’un doit aller fouiller dans mon code pour le comprendre, alors j’ai échoué.

  • Même avec une API très claire, le code interne peut rester difficile à comprendre. En apparence tout peut sembler bien fonctionner, alors qu’en pratique il faut souvent plonger jusqu’à l’intérieur.

• J’aime beaucoup ce texte, car il résume très bien mon expérience. La plupart des méthodologies de programmation qu’on m’a enseignées officiellement deviennent contre-productives dès que quelqu’un d’autre doit lire mon code. Le code qui cache sa complexité, comme en Rust ou en C++, est difficile, et quand je vois une structure comme le C, où l’on ne peut pas enfouir le code sous six couches de templates, cela me rassure presque.

  • Ravi que cela fasse écho à votre expérience. J’ai moi aussi aimé le C pour cette raison, et récemment je suis passé à Golang, dont la simplicité me plaît beaucoup.

• L’idée qu’il faut traiter l’accessibilité du code comme un citoyen de première classe me parle énormément. Les règles doivent servir de guide, et les vrais experts sont ceux qui savent, selon le contexte, quand les enfreindre ou les compléter pour que le code reste facile à lire. Au final, ce qui compte, c’est la capacité à ressentir intuitivement la charge cognitive du code et les compromis qu’elle implique. Qu’il s’agisse de duplication ou d’abstraction, il faut toujours penser à la personne suivante, y compris soi-même dans six mois. Quant aux demandes de créer encore une nouvelle règle, elles ne font que répéter le problème sous une autre forme. Au-delà des lignes directrices de base, tout relève de la tacit knowledge, c’est-à-dire du savoir implicite qui vient de l’expérience. Avec le temps, on finit par sentir soi-même quel code est bon ou mauvais. Au bout du compte, il faut l’éprouver directement.

  • Je suis d’accord sur le fond concernant l’accessibilité du code, mais je trouve dommage que l’auteur néglige le germane overhead (la consommation de ressources cognitives du destinataire). Pour améliorer l’accessibilité du code, il faut finalement prendre en compte les trois types d’overhead : intrinsic, extraneous et germane.

• On dit souvent qu’il faut documenter le « pourquoi », mais personnellement j’ai du mal à séparer le « pourquoi » du « quoi », donc je consigne les deux. Les pires commentaires sont du genre :

  x = 4 // assigne 4 à x 
  

  Ce genre de mélange entre code et commentaire est difficile à lire et impose un changement de contexte permanent. Je préfère plutôt quelque chose comme :

  // pourquoi on fait ceci, et ce que cela va accomplir
  setup();
  t = setupThing();
  t.useThing(42);
  t.theWidget(need=true);
  ...
  

  où les commentaires et le code sont clairement séparés. Cela dit, même écrire le « quoi » vaut bien mieux que ne rien écrire du tout, et réduit la charge cognitive.

  • Ce type de commentaires est généralement difficile à maintenir : comme l’implémentation change cinq fois par an, ils vieillissent vite et deviennent source de confusion. Dans mes projets récents, j’ai supprimé la plupart des commentaires pour ne garder que la logique vraiment difficile et la documentation de plus haut niveau.

  • Je pense qu’il y a des cas où il faut documenter les deux (why/what). Parfois il faut expliciter la raison, parfois il faut clarifier le fonctionnement. J’ai l’impression qu’aujourd’hui on sous-estime la valeur des commentaires. Il n’est pas nécessaire d’en mettre à chaque ligne, mais la plupart des codes dits « auto-documentés » ne sont pas si faciles à lire que ça.

  • En ce moment, j’ai surtout l’impression que le plus difficile est de décider ce qu’il faut laisser dans le code, et ce qu’il faut mettre dans un document de conception ou une documentation technique. Ma conclusion, c’est qu’il vaut mieux utiliser les commentaires dans le code pour expliquer des intentions non intuitives ou cachées. Par exemple : « on mémoïse ceci pour telle raison ».

  • Le style de commentaire x=4 façon ChatGPT m’a fait rire. En revanche, le défaut de l’approche proposée, c’est le risque que les commentaires vieillissent et ne correspondent plus au code. Quand on modifie le code, il faut absolument mettre les commentaires à jour aussi.

  • Je ne suis pas programmeur de formation mais physicien, et quand j’ajoute des commentaires, j’essaie de plus en plus d’adopter cette manière de faire. Quand j’étais étudiant, la règle implicite pour avoir de bonnes notes était de mettre beaucoup de commentaires, quoi qu’il arrive.