À la défense du code propre : plus de 100 conseils intemporels d’Oncle Bob

Code propre de Robert C. Martin est le livre de programmation le plus recommandé de tous les temps. Recherchez n’importe quelle liste des « meilleurs livres pour les ingénieurs logiciels », et vous êtes presque assuré de trouver ce livre sur la liste.

Et pourtant, certaines personnes aiment détester Code propre, allant même jusqu’à dire qu’il est probablement temps d’arrêter de recommander Code propre. Je dirais que des sentiments comme celui-ci sont profondément erronés.

Oui, certains des conseils du livre sont discutables. Oui, une partie du contenu semble datée ou n’a pas bien vieilli avec le temps. Oui, certains exemples prêtent à confusion. Tout ceci est vrai. Mais ne soyons pas si prompts à écarter tous les bon conseils que le livre a à offrir!

Ignorer complètement un livre simplement à cause de quelques mauvaises idées est un exemple parfait de plusieurs distorsions cognitives : filtrage mental, grossissement et actualisation du positif, pour n’en nommer que quelques-unes.

En fait, Oncle Bob et les autres auteurs contributeurs ont pris soin de traiter ce problème de manière préventive dans le premier chapitre du livre :

Bon nombre des recommandations contenues dans ce livre sont controversées. Vous ne serez probablement pas d’accord avec tous. Vous pourriez être violemment en désaccord avec certains d’entre eux. C’est très bien. Nous ne pouvons pas revendiquer l’autorité finale. D’un autre côté, les recommandations de ce livre sont des choses auxquelles nous avons longuement réfléchi. Nous les avons apprises au cours de décennies d’expérience et d’essais et d’erreurs répétés. Donc, que vous soyez d’accord ou non, il serait dommage que vous ne voyiez pas et ne respectiez pas notre point de vue.

Alors sans plus tarder, considérons tous les conseils intemporels qui Code propre a à offrir ! Nous allons parcourir le livre, chapitre par chapitre, en résumant bon nombre des idées présentées par Oncle Bob.

Chapitre 1 : Nettoyer le code

Le coût total de possession d’un mess se compose au fil du temps.
Il est très difficile de reconstruire un système hérité à partir de zéro. La refactorisation et les améliorations incrémentielles sont souvent la meilleure voie à suivre.
Dans les bases de code désordonnées, cela peut prendre des jours ou des semaines pour accomplir des tâches qui ne devraient prendre que des heures.
Prenez le temps d’aller vite.
Un code propre fait bien une chose. Un mauvais code essaie d’en faire trop.
Le code propre est bien testé.
Lors de la lecture de code bien écrit, chaque fonction fait à peu près ce à quoi vous vous attendiez.
Si vous n’êtes pas d’accord avec un principe selon lequel quelqu’un avec des décennies d’expérience enseigne, vous feriez bien de considérer au moins son point de vue avant de l’ignorer.
Le code est lu beaucoup plus souvent qu’il n’est écrit.
Un code qui est plus facile à lire est plus facile à changer.
Laissez la base de code meilleure que vous ne l’avez trouvée (The Boy Scout Rule).

Chapitre 2 : Noms significatifs

Choisissez soigneusement les noms de vos variables.
Choisir de bons noms est difficile.
Le nom d’une variable ou d’une fonction doit vous dire de quoi il s’agit et comment elle est utilisée.
Évitez les noms de variables à caractère unique, à l’exception des noms couramment utilisés comme i pour la variable compteur dans une boucle.
Évitez d’utiliser des abréviations dans les noms de variables.
Les noms de variables doivent être prononçables pour que vous puissiez en parler et les prononcer à voix haute.
Utilisez des noms de variables facilement consultables.
Les classes et les objets doivent avoir des noms qui sont des noms.
Les méthodes et les fonctions doivent avoir des noms qui sont des verbes ou des paires verbe-nom.

Chapitre 3 : Fonctions

Les fonctions doivent être petites.
Les fonctions doivent faire une chose.
Les fonctions doivent avoir des noms descriptifs. (Répété du chapitre 2)
Extrayez le code dans le corps des instructions if/else ou basculez dans des fonctions clairement nommées.
Limitez le nombre d’arguments qu’une fonction accepte.
Si une fonction a besoin de beaucoup d’arguments de configuration, envisagez de les combiner en une seule variable d’options de configuration.
Les fonctions doivent être pures, ce qui signifie qu’elles n’ont pas d’effets secondaires et ne modifient pas leurs arguments d’entrée.
Une fonction doit être une commande ou une requête, mais pas les deux (Command Query Separation).
Lancez des erreurs et des exceptions plutôt que de renvoyer des codes d’erreur.
Extrayez le code dupliqué dans des fonctions clairement nommées (Ne vous répétez pas).
Les tests unitaires facilitent le refactoring.

Chapitre 4 : Commentaires

Les commentaires peuvent mentir. Ils peuvent être erronés au départ, ou ils peuvent être exacts à l’origine, puis devenir obsolètes au fil du temps à mesure que le code associé change.
Utilisez des commentaires pour décrire Pourquoi quelque chose est écrit comme il est, pas pour expliquer Quel est passe.
Les commentaires peuvent souvent être évités en utilisant des variables clairement nommées et en extrayant des sections de code dans des fonctions clairement nommées.
Préfixez vos commentaires TODO de manière cohérente pour faciliter leur recherche. Revoyez et nettoyez vos commentaires TODO périodiquement.
N’utilisez pas Javadocs juste pour le plaisir de les utiliser. Les commentaires qui décrivent ce que fait une méthode, les arguments qu’elle prend et ce qu’elle renvoie sont souvent au mieux redondants et au pire trompeurs.
Les commentaires doivent inclure toutes les informations pertinentes et le contexte dont une personne lisant le commentaire aura besoin. Ne soyez pas paresseux ou vague lorsque vous écrivez un commentaire.
Les commentaires des journaux et les commentaires des auteurs de fichiers sont inutiles en raison du contrôle de version et du blâme de git.
Ne commentez pas le code mort. Supprimez-le simplement. Si vous pensez avoir besoin du code à l’avenir, c’est à cela que sert le contrôle de version.

Chapitre 5 : Formatage

En équipe, choisissez un ensemble de règles pour formater votre code, puis appliquez ces règles de manière cohérente. Les règles sur lesquelles vous êtes d’accord importent peu, mais vous devez vous mettre d’accord.
Utilisez un formateur de code automatisé et un linter de code. Ne comptez pas sur les humains pour détecter et corriger manuellement chaque erreur de formatage. C’est inefficace, improductif et une perte de temps lors des revues de code.
Ajoutez des espaces verticaux dans votre code pour séparer visuellement les blocs de code associés. Une seule nouvelle ligne entre les groupes est tout ce dont vous avez besoin.
Les petits fichiers sont plus faciles à lire, à comprendre et à parcourir que les gros fichiers.
Les variables doivent être déclarées à proximité de l’endroit où elles sont utilisées. Pour les petites fonctions, c’est généralement en haut de la fonction.
Même pour les fonctions courtes ou les instructions if, formatez-les toujours correctement plutôt que de les écrire sur une seule ligne.

Chapitre 6 : Objets et structures de données

Les détails d’implémentation dans un objet doivent être cachés derrière l’interface de l’objet. En fournissant une interface aux consommateurs de l’objet à utiliser, vous facilitez la refactorisation ultérieure des détails de l’implémentation sans provoquer de modifications avec rupture. Les abstractions facilitent la refactorisation.
Un morceau de code donné ne devrait pas connaître les éléments internes d’un objet avec lequel il travaille.
Lorsque vous travaillez avec un objet, vous devez lui demander d’effectuer des commandes ou des requêtes, pas de lui poser des questions sur ses éléments internes.

Chapitre 7 : Gestion des erreurs

La gestion des erreurs ne doit pas masquer le reste du code du module.
Lancez des erreurs et des exceptions plutôt que de renvoyer des codes d’erreur. (Répété du chapitre 3)
Écrivez des tests qui forcent les erreurs pour vous assurer que votre code gère plus que le chemin heureux.
Les messages d’erreur doivent être informatifs, fournissant tout le contexte dont une personne recevant le message d’erreur aurait besoin pour un dépannage efficace.
L’encapsulation d’API tierces dans une fine couche d’abstraction facilite le remplacement d’une bibliothèque par une autre à l’avenir.
L’encapsulation des API tierces dans une fine couche d’abstraction facilite la simulation de la bibliothèque pendant les tests.
Utilisez le modèle de cas spécial ou le modèle d’objet nul pour gérer un comportement exceptionnel, comme lorsque certaines données n’existent pas.

Chapitre 8 : Limites

Les bibliothèques tierces vous aident à expédier votre produit plus rapidement en vous permettant d’externaliser diverses préoccupations.
Écrivez des tests pour vous assurer que votre utilisation d’une bibliothèque tierce donnée fonctionne correctement.
Utilisez le modèle Adapter pour combler le fossé entre l’API d’une bibliothèque tierce et l’API que vous souhaitez qu’elle ait.
L’encapsulation d’API tierces dans une fine couche d’abstraction facilite le remplacement d’une bibliothèque par une autre à l’avenir. (Répété du chapitre 7)
L’encapsulation des API tierces dans une fine couche d’abstraction facilite la simulation de la bibliothèque pendant les tests. (Répété du chapitre 7)
Évitez de trop faire connaître à votre application les détails d’une bibliothèque tierce donnée.
Il vaut mieux dépendre de quelque chose que vous contrôlez que de dépendre de quelque chose que vous ne contrôlez pas.

Chapitre 9 : Tests unitaires

Le code de test doit être aussi propre que le code de production (à quelques exceptions près, impliquant généralement la mémoire ou l’efficacité).
À mesure que le code de production change, le code de test change également.
Les tests aident à garder votre code de production flexible et maintenable.
Les tests permettent le changement en vous permettant de remanier en toute confiance sans craindre de casser des choses sans le savoir.
Structurez vos tests à l’aide du modèle Arrange-Act-Assert (également appelé Build-Operate-Check, Setup-Exercise-Verify ou Given-When-Then).
Utilisez des fonctions spécifiques au domaine pour rendre les tests plus faciles à écrire et à lire.
Évaluer un seul concept par test.
Les tests doivent être rapides.
Les tests doivent être indépendants.
Les tests doivent être reproductibles.
Les tests doivent être auto-validants.
Les tests doivent être écrits en temps opportun, soit peu de temps avant ou après l’écriture du code de production, et non des mois plus tard.
Si vous laissez vos tests pourrir, votre code pourrira aussi.

Chapitre 10 : Cours

Les classes doivent être petites.
Les classes ne devraient être responsables que d’une seule chose et ne devraient avoir qu’une seule raison de changer (principe de responsabilité unique).
Si vous ne pouvez pas penser à un nom clair pour une classe, c’est probablement trop gros.
Votre travail n’est pas terminé une fois qu’un morceau de code fonctionne. Votre prochaine étape consiste à refactoriser et à nettoyer le code.
L’utilisation de nombreuses petites classes au lieu de quelques grandes classes dans votre application réduit la quantité d’informations qu’un développeur doit comprendre lorsqu’il travaille sur une tâche donnée.
Avoir une bonne suite de tests en place vous permet de refactoriser en toute confiance lorsque vous divisez les grandes classes en classes plus petites.
Les classes doivent être ouvertes pour extension mais fermées pour modification (principe ouvert-fermé).
Les interfaces et les classes abstraites fournissent des coutures qui facilitent les tests.

Chapitre 11 : Systèmes

Utilisez l’injection de dépendances pour donner aux développeurs la possibilité de transmettre n’importe quel objet avec une interface correspondante à une autre classe.
Utilisez l’injection de dépendances pour créer des jointures d’objets dans votre application afin de faciliter les tests.
Les systèmes logiciels ne sont pas comme un bâtiment qui doit être conçu en amont. Ce sont plutôt des villes qui grandissent et s’étendent au fil du temps, s’adaptant aux besoins actuels.
Retardez la prise de décision jusqu’au dernier moment responsable.
Utilisez un langage spécifique au domaine afin que les experts du domaine et les développeurs utilisent la même terminologie.
Ne compliquez pas trop votre système. Utilisez la chose la plus simple qui fonctionne.

Chapitre 12 : Émergence

Les systèmes qui ne sont pas testables ne sont pas vérifiables, et les systèmes qui ne sont pas vérifiables ne devraient jamais être déployés.
L’écriture de tests conduit à de meilleures conceptions, car le code facile à tester utilise souvent l’injection de dépendances, les interfaces et l’abstraction.
Une bonne suite de tests élimine votre peur de casser l’application lors de la refactorisation.
La duplication dans votre code crée plus de risques, car il y a plus d’endroits dans le code à modifier et plus d’endroits dans le code pour les bogues à cacher.
Il est facile de comprendre le code que vous êtes en train d’écrire parce que vous avez été profondément impliqué dans sa compréhension. Il n’est pas si facile pour les autres d’acquérir rapidement le même niveau de compréhension.
La majorité du coût d’un projet logiciel se situe dans la maintenance à long terme.
Les tests agissent comme une documentation vivante de la façon dont votre application devrait (et se comporte) se comporter.
Ne bougez pas dès que vous obtenez votre code…