Publish Tidy First, by Kent Beck

content/technologeek/books/2023-03-23-a-philosophy-of-software-design/index.md

@@ -1,5 +1,6 @@
 ---
 title: A Philosophy of Software Design
+writer: John Ousterhout
 ---
 
 Ca papote de beaucoup de sujets intéressants, il y a un enooooorme chapitre sur les commentaires dans le code qui se solde par « l’objectif des commentaires est de s’assurer que la structure et le comportement d’un système sont limpides pour le lecteur (ce qui ne me convient pas vraiment - je serais plutôt d'avis à limiter au maximum les commentaires, pour éviter les redondances et limiter les incohérences entre commentaires et code).

content/technologeek/books/2024-02-04-tidy-first/index.md

@@ -7,14 +7,17 @@ tags: [dette technique, Pareto]
 > Don't make software design such a big deal that you're in danger of not doing it
 > -- page 23, chapitre II
 
-La complexité d'un programme informatique dépend de la manière dont il est organisé et découpé, comment ces différentes parties sont couplées entre elles, et combien elles sont en cohésion les unes avec les autres.
+La complexité d'un programme informatique dépend de la manière dont il est organisé et découpé, de la manière dont ces différentes parties sont couplées entre elles, et combien elles sont en cohésion les unes avec les autres.
+
 La **cohésion** correspond au degré d'adéquation entre les différents éléments d'un même module.
 En terme de programmation, ceci correspond au fait que ces éléments évoluent ensemble et forment un tout cohérent.
-Le **couplage** correspond à la nécessité pour un module de disposer d'informations appartenant à un autre module [^1].
-Ce couplage sera représenté par la nécessité de modifier un élément alors que nous avions prévu d'en modifier un autre.
-Il s'agit en gros de la manière dont notre cerveau sera à même de traiter la complexité d'une architecture - et il est donc dans l'intérêt de tout le monde de faire en sorte que le nôtre puisse être abordé de la manière la plus simple possible.
+Le **couplage** correspond à la nécessité pour un module de disposer d'informations appartenant à un autre module[^1].
 
-[^1] Un très bon article sur [Baeldung](https://www.baeldung.com/cs/cohesion-vs-coupling) explique très bien cette distinction, avec plusieurs exemples concrets.
+Le couplage sera donc impacté par la nécessité de modifier un élément alors que nous avions prévu d'en modifier un autre - bien que cela puisse être nécessaire (une fonction pouvant être appelée depuis un autre module, en modifier la signature nécessitera évidemment de modifier également tous les appels y faisant référence), il peut aussi s'agir de dette technique, de mauvaises décisions passées ou d'une architecture pas assez ouverte.
+
+Ces deux concepts (couplage et cohésion) agissent sur la manière dont notre cerveau sera à même de traiter la complexité d'une architecture - et il est donc dans l'intérêt de tout le monde de faire en sorte que la nôtre puisse être abordée de la manière la plus simple possible.
+
+[^1]: Un très bon article sur [Baeldung](https://www.baeldung.com/cs/cohesion-vs-coupling) explique très bien cette distinction entre couplage et cohésion, avec plusieurs exemples concrets.
 
 Le développement logiciel est un processus humain : il ne s'agit pas juste de créer un ensemble d'instructions à destination d'un ordinateur, mais plutôt que les intentions prévues à destination d'un ordinateur, puissent être comprises par d'autres personnes.
 
@@ -27,7 +30,7 @@ Les logiciels apportent de la valeur de deux manières :
 
 Les options (et particulièrement les greffons et possibilités d'extensions) constituent la magie économique d'un développement.
 Ce qui interfère avec les options sont les changements de structure ou d'organisation : un employé qui quitte l'entreprise, une distance (de compréhension) avec les utilisateurs ou le coût d'un changement à appliquer.
-En cas de situations chaotiques, créer des options sera votre meilleur allié : cela vous permettra de proposer une base concrète, et d'attendre que la situation se calme avant de pouvoir la faire évoluer.
+En cas de situations chaotiques, créer des options sera votre meilleur allié : cela vous permettra de proposer une base concrète, et d'attendre que la situation évolue avant de pouvoir prendre une décision.
 
 ## Nettoyage de code
 
@@ -96,9 +99,10 @@ Le langage `C#` permet de créer des espaces de noms indépendants de l'emplacem
 
 A termes, tout ceci peut également facilier le réarrangement de ces éléments.
 
-### Auto-explication des variables,
-
+### Auto-explication des variables
 
+La nomenclature à attribuer aux variables touche avant tout à la compréhension générale, afin d'éviter d'avoir des lignes gigantesques - tout en assurant malgré tout une bonne compréhension contextuelle, en évitant les `a`, `b` et `tmp`.
+Combiner une bonne nomenclature avec des namespaces est une bonne idée.
 
 ### One big pile
 
@@ -106,12 +110,19 @@ L'objectif du nettoyage de code est d'apporter une forme de paix et de satisfact
 _A contrario_, y passer du temps à chaque revue de code ne va faire qu'ajouter de la frustration et de l'énervement, car ces revues doivent tenir compte d'autres éléments (couplage, découplage, cohésion, ...).
 Il faut faire attention à ne pas sombrer en abîme.
 
-### Commentaires d'explication
+Lorsqu'un nettoyage est nécessaire et que le code ressemble trop à une assiette de spaghettis, une bonne manière de faire consiste à tout remettre à plat, en remontant le contenu des fonctions et méthodes au sein d'une seule et même fonction.
+De cette manière, il doit être plus facile d'avancer et de réorganiser le contenu, plutôt que de se perdre parmi les différentes fonctions appelées.
 
-Il faut faire attention si des commentaires sont présents pour expliquer le fonctionnement d'une méthode ou d'un morceau de code, car cela pourra créer du couplage entre le code et ses commentaires - et il n'existe pour le moment
+![](one-big-pile.drawio.png)
 
-### Suppression de commentaires récurrents
+### Commentaires
 
+Quand un commentaire explique le fonctionnement interne d'un morceau de code, supprimez-le ; il est possible d'expliquer exactement ce que font quelques lignes de code au travers de phrases, mais il n'existe aucun mécanisme permettant de vérifier et valider que l'explication colle précisément avec la réalité du résultat.
+Ceci entraîne un couplage entre les commentaires et le code lui-même, et doit être évité.
+
+Un commentaire doit être aussi petit et précis que possible, et ne communiquer que des informations qui ne peuvent être déduites au travers du code.
+
+Par contre, lorsqu'une défectuosité est détectée, et même si cela ajoute un peu de couplage entre le code et les commentaires, il vaut mieux expliquer le point d'accroche que de le laisser de côté et de devoir s'y repencher plus tard.
 
 ## Coûts d'un développement informatique
 
@@ -119,6 +130,19 @@ L'équivalence de Constantine indique le coût du développement d'une applicati
 Après la *release* initiale, un gros travail doit être réalisé afin de stabiliser l'existant.
 Ensuite seulement, cette maintenance se stabilisera.
 
+![](development-cost-0.drawio.png)
+
 Une autre manière de visualiser ceci consiste à regarder le cumul des coûts :
 
 ![](development-cost.drawio.png)
+
+L'équation à résoudre intervient lorsque le coût d'une nouvelle fonctionnalité _sans refactoring_ est inférieur au coût de cette même fonctionnalité _avec_ nettoyage.
+Dans l'autre cas, il n'y a absolument pas à réfléchir.
+
+La réflexion devient plus complexe lorsque l'ajout d'une fonctionnalité _avec_ refactoring permettra de gagner du temps sur l'ensemble des fonctionnalités à venir.
+Dans ce cas précis, on parle effectivement d'investissement et de valeur ajoutée, avec une fonction exponentielle sur la valeur des investissements passés et options futures.
+
+## Conclusions
+
+Sympa à lire, pas trop touffu, pas trop prise de tête, et rédigé de manière suffisamment accessible que pour être lu par n'importe quel développeur ayant déjà quelques années d'expériences.
+Reste à suivre les quelques conseils prodigués au fil des pages, et on sera bons 😉