Pause café #103. Pour la défense du « Clean Code » : 100 astuces intemporelles

Source : Hackernoon « Clean Code » de Robert C. Martin est le livre de programmation le plus recommandé de tous les temps. Recherchez des livres en utilisant la requête « meilleurs livres pour les développeurs de logiciels » et vous êtes presque assuré de trouver ce livre dans les résultats de recherche. Et même si certaines personnes estiment que le Clean Code ne mérite pas qu’on y prête attention, je dirais que de tels sentiments sont profondément erronés. Oui, certains conseils du livre sont discutables. Oui, certains contenus semblent obsolètes. Oui, certains exemples prêtent à confusion. Tout est vrai. Mais ne négligeons pas si vite les nombreux conseils utiles que propose ce livre ! Ignorer complètement le Clean Code simplement à cause de quelques mauvaises idées n’est pas la meilleure solution. Alors, sans plus tarder, regardons les meilleurs conseils que Clean Code a à offrir ! Nous passerons en revue chaque chapitre, résumant les idées proposées par Oncle Bob et ses co-auteurs.

Chapitre 1 : Code propre

1. La quantité globale de désordre augmente avec le temps.

2. Restaurer un système obsolète à partir de zéro est très difficile. La refactorisation et les améliorations incrémentielles seront la meilleure option pour cela.

3. Dans une base de code désordonnée, des tâches qui ne devraient prendre que quelques heures peuvent prendre des jours, voire des semaines.

4. Prenez le temps d'agir vite.

5. Un code propre fait bien une chose. Un mauvais code essaie d’en faire trop.

6. Le code propre est bien testé.

7. Lors de la lecture d'un code bien écrit, chaque fonction fait à peu près ce à quoi vous vous attendez.

8. Si vous n’êtes pas d’accord avec un principe enseigné par une personne ayant des années d’expérience, vous devriez au moins considérer son point de vue avant de l’ignorer.

9. Le code est lu beaucoup plus souvent qu’il n’est écrit.

10. Un code plus facile à lire est plus facile à modifier.

11. Laissez la base de code meilleure que lorsque vous l'avez trouvée (Boy Scout Rule).

Chapitre 2 : La signification des noms

1. Choisissez soigneusement vos noms de variables.

2. Choisir de bons noms est difficile.

3. Le nom d'une variable ou d'une fonction doit indiquer de quoi il s'agit et comment elle est utilisée.

4. Évitez d'utiliser des noms de variables à un seul caractère, à l'exception des noms couramment utilisés, tels que i pour une variable compteur dans une boucle.

5. Évitez d'utiliser des abréviations dans les noms de variables.

6. Les noms de variables doivent être prononçables afin que vous puissiez en parler et les prononcer à voix haute.

7. Utilisez des noms de variables faciles à trouver.

8. Les classes et les objets doivent avoir des noms sous forme de noms.

9. Les noms de méthodes et de fonctions doivent être des verbes ou des paires verbe-nom.

Chapitre 3 : Fonctions

1. Les fonctions doivent être petites.

2. La fonction doit effectuer une action.

3. Les fonctions doivent avoir des noms descriptifs.

4. Extrayez le code dans le corps if/else ou transformez les instructions en fonctions clairement nommées.

5. Limitez le nombre d'arguments qu'une fonction prend.

6. Si une fonction nécessite de nombreux arguments de configuration, envisagez de les combiner en une seule variable de paramètres de configuration.

7. 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.

8. La fonction doit être une commande ou une requête, mais pas les deux à la fois (Command Query Separation).

9. Il est préférable de supprimer les erreurs et exceptions du code plutôt que de laisser des erreurs dans le code.

10. Extrayez le code en double dans des fonctions clairement nommées (Ne vous répétez pas).

11. Les tests unitaires facilitent la refactorisation.

Chapitre 4 : Commentaires

1. Les commentaires peuvent être incorrects. Ils peuvent être erronés au départ, ou ils peuvent être initialement précis, puis devenir obsolètes au fil du temps à mesure que le code change.

2. Utilisez des commentaires pour décrire pourquoi c'est écrit tel quel, plutôt que d'expliquer ce qui se passe.

3. 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.

4. Préfixez les commentaires TODO avec des préfixes cohérents pour les rendre plus faciles à trouver. Examinez et nettoyez périodiquement vos commentaires TODO.

5. N'utilisez pas Javadocs juste pour le plaisir de les utiliser. Les commentaires décrivant ce que fait une méthode, les arguments qu'elle prend et ce qu'elle renvoie sont au mieux redondants et au pire trompeurs.

6. Les commentaires doivent inclure toutes les informations pertinentes et le contexte dont le lecteur aura besoin. Ne soyez pas paresseux lorsque vous écrivez un commentaire.

7. Les commentaires du journal et les commentaires de l'auteur du fichier ne sont pas nécessaires en raison du contrôle de version et du blâme de git.

8. Ne commentez pas le code mort. Supprimez-le simplement. Si vous pensez que vous aurez besoin du code à l’avenir, c’est à cela que sert le contrôle de version.

Chapitre 5 : Formatage

1. En équipe, sélectionnez un ensemble de règles pour formater votre code, puis appliquez ces règles de manière cohérente. Quelles que soient les règles avec lesquelles vous êtes d’accord, vous devez parvenir à un accord.

2. Utilisez le formatage automatique du code et un analyseur de code. Ne comptez pas sur les gens pour rechercher et corriger manuellement chaque erreur de formatage. Ceci est inefficace, improductif et constitue une perte de temps lors de la révision du code.

3. Ajoutez des espaces verticaux entre les lignes de code pour séparer visuellement les blocs de code associés. Tout ce dont vous avez besoin est de créer une nouvelle ligne entre les groupes.

4. Les petits fichiers sont plus faciles à lire, à comprendre et à déplacer que les gros fichiers.

5. Les variables doivent être déclarées à proximité de l'endroit où elles sont utilisées. Pour les petites fonctions, cela se trouve généralement en haut de la fonction.

6. Même pour les fonctions courtes ou les instructions if, formatez-les correctement plutôt que de les écrire sur une seule ligne.

Chapitre 6 : Objets et structures de données

1. Les détails d'implémentation dans un objet doivent être cachés derrière l'interface de l'objet. En fournissant une interface à utiliser par les consommateurs d'un objet, vous facilitez la refactorisation ultérieure des détails d'implémentation sans provoquer de modifications radicales. Les abstractions facilitent la refactorisation.

2. Tout morceau de code donné ne devrait avoir aucune connaissance des éléments internes de l'objet sur lequel il opère.

3. Lorsque vous travaillez avec un objet, vous devez lui demander d'exécuter une commande ou une requête, plutôt que de lui poser des questions sur ses composants internes.

Chapitre 7 : Correction des erreurs

1. La gestion des erreurs ne doit pas interférer avec le reste du code du module.

2. Il est préférable de supprimer les erreurs et exceptions du code plutôt que de laisser des erreurs dans le code.

3. Écrivez des tests avec des erreurs pour vous assurer que votre code les identifie et ne les manque pas.

4. Les messages d'erreur doivent être informatifs, avec tout le contexte nécessaire dont quelqu'un pourrait avoir besoin pour résoudre efficacement les problèmes.

5. Envelopper les API tierces dans une fine couche d'abstraction facilite le remplacement futur d'une bibliothèque par une autre.

6. Envelopper les API tierces dans une fine couche d'abstraction facilite la simulation de la bibliothèque pendant les tests.

7. Utilisez le modèle Cas spécial ou le modèle Objet nul pour gérer un comportement exceptionnel, par exemple lorsque certaines données n'existent pas.

Chapitre 8 : Limites

1. Les bibliothèques tierces contribuent à accélérer la livraison des produits en vous permettant d'externaliser diverses tâches.

2. Écrivez des tests pour vous assurer que vous utilisez correctement la bibliothèque tierce.

3. Utilisez le modèle d'adaptateur pour combler le fossé entre l'API d'une bibliothèque tierce et l'API que vous souhaitez avoir.

4. Envelopper les API tierces dans une fine couche d'abstraction facilite le remplacement futur d'une bibliothèque par une autre. (Répétition du chapitre 7)

5. Envelopper les API tierces dans une fine couche d'abstraction facilite la simulation de la bibliothèque pendant les tests. (Répétition du chapitre 7)

6. Essayez de ne pas donner trop d'informations à votre application sur les détails d'une bibliothèque tierce.

7. Il vaut mieux dépendre de ce que l’on contrôle que de ce que l’on ne contrôle pas.

Chapitre 9 : Tests unitaires

1. Le code de test doit être aussi propre que le code de production (à quelques exceptions près, généralement liées à la mémoire ou à l'efficacité).

2. À mesure que le code de production change, le code de test évolue également.

3. Les tests aident à garder votre code de production flexible et maintenable.

4. Les tests vous permettent d'apporter des modifications, vous permettant ainsi de refactoriser en toute confiance sans craindre de ne pas le remarquer vous-même.

5. Structurez vos tests à l'aide du modèle Arrange-Act-Assert (également connu sous le nom de Build-Operate-Check, Setup-Exercise-Verify ou Given-When-Then).

6. Utilisez des fonctions spécifiques au domaine pour faciliter l'écriture et la lecture des tests.

7. Notez un concept par test.

8. Les tests doivent être rapides.

9. Les tests doivent être indépendants.

10. Les tests doivent être reproductibles.

11. Les tests ne devraient pas nécessiter de confirmation.

12. Les tests doivent être rédigés en temps opportun, peu de temps avant ou après l'écriture du code de production, et non des mois plus tard.

13. Si vos tests sont mauvais, attendez-vous à ce qu'il y ait des bugs dans votre code.

Chapitre 10 : Cours

1. Les classes devraient être petites.

2. 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).

3. Si vous ne parvenez pas à trouver un nom clair pour la classe, c'est probablement trop gros.

4. Votre travail ne se termine pas lorsque vous faites fonctionner un morceau de code. La prochaine étape consistera à refactoriser et nettoyer le code.

5. L'utilisation de nombreuses petites classes au lieu de plusieurs 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.

6. Avoir une bonne suite de tests vous permet de refactoriser en toute confiance lorsque vous divisez de grandes classes en classes plus petites.

7. Les classes doivent être ouvertes à l’extension, mais fermées à la modification (principe ouvert-fermé).

8. Les interfaces et les classes abstraites créent des coutures qui facilitent les tests.

Chapitre 11 : Systèmes

1. Utilisez l'injection de dépendances pour donner aux développeurs la flexibilité de transmettre n'importe quel objet doté de l'interface appropriée à une autre classe.

2. Utilisez l'injection de dépendances pour créer des interfaces entre les objets de votre application afin de faciliter les tests.

3. Les systèmes logiciels ne sont pas comme un bâtiment qui doit être conçu à l’avance. Elles ressemblent davantage à des villes qui grandissent et s’étendent au fil du temps, s’adaptant aux besoins actuels.

4. Remettez la prise de décision au dernier moment critique.

5. Utilisez un langage spécifique au domaine afin que les experts du domaine et les développeurs utilisent la même terminologie.

6. Ne compliquez pas trop votre système. Utilisez la chose la plus simple qui fonctionne.

Chapitre 12 : Déploiement

1. Les systèmes qui ne peuvent pas être testés ne peuvent pas être vérifiés, et les systèmes qui ne peuvent pas être vérifiés ne doivent jamais être déployés.

2. L'écriture de tests conduit à une meilleure conception, car le code facile à tester utilise souvent l'injection de dépendances, les interfaces et l'abstraction.

3. Un bon ensemble de tests éliminera la crainte de casser votre application lors de la refactorisation.

4. La duplication de code crée plus de risques car il y a plus d'endroits dans le code qui peuvent être modifiés et encore plus d'endroits où les erreurs peuvent être masquées.

5. Le code que vous écrivez maintenant est plus facile à comprendre car vous êtes profondément impliqué dans sa compréhension. Il n’est pas facile pour les autres d’atteindre rapidement le même niveau de compréhension.

6. La majeure partie du coût d'un projet logiciel est liée à la maintenance à long terme.

7. Les tests servent de documentation vivante sur la façon dont votre application devrait (et se comporte) se comporter.

8. N'allez pas plus loin une fois que votre code fonctionne. Prenez le temps de le rendre plus clair et plus compréhensible.

9. La prochaine personne qui lira votre code dans un avenir proche sera probablement vous. Soyez gentil avec votre futur moi en écrivant un code facile à comprendre.

10. Résistez au dogme. Adoptez le pragmatisme.

11. Il faut des décennies pour devenir un très bon ingénieur logiciel. Vous pouvez accélérer votre courbe d'apprentissage en apprenant auprès des experts autour de vous et en apprenant les modèles de conception couramment utilisés.

Chapitre 13 : Parallélisme

1. Écrire du code parallèle est difficile.

2. Les bugs occasionnels et les problèmes difficiles à reproduire sont souvent des problèmes de concurrence.

3. Les tests ne garantissent pas que votre application sera exempte de bogues, mais ils minimiseront les risques.

4. Découvrez les problèmes de concurrence courants et leurs solutions possibles.

Chapitre 14 : Raffinement séquentiel

1. Un code propre ne démarre généralement pas avec une page vierge. Vous écrivez d’abord une solution approximative, puis vous la refactorisez pour la rendre plus propre.

2. C'est une erreur d'arrêter de travailler sur le code une fois qu'il a commencé à fonctionner. Prenez le temps de l'améliorer encore une fois qu'il fonctionne déjà.

3. Les troubles s’amplifient progressivement.

4. Si vous vous trouvez dans une impasse où l'ajout de fonctionnalités est trop difficile ou prend trop de temps, arrêtez d'écrire des fonctionnalités et commencez à refactoriser.

5. Un changement progressif est souvent préférable à une reconstruction à partir de zéro.

6. Utilisez le développement piloté par les tests (TDD) pour apporter un grand nombre de très petites modifications.

7. Une bonne conception logicielle implique de séparer les problèmes de votre code et de diviser le code en modules, classes et fichiers plus petits.

8. Il est plus facile de nettoyer un dégât immédiatement après l'avoir fait que de le nettoyer plus tard.

Chapitre 15 : Éléments internes de JUnit

1. Les noms de variables négatifs ou les expressions conditionnelles sont un peu plus difficiles à comprendre que les noms positifs.

2. La refactorisation est un processus itératif plein d'essais et d'erreurs.

3. Laissez la base de code meilleure que lorsque vous l'avez trouvée (Boy Scout Rule). (Répété du chapitre 1)

Chapitre 16 : Refactorisation de SerialDate

1. Les révisions de code et les critiques de notre code nous rendent meilleurs, et nous devrions nous en féliciter.

2. Faites d’abord fonctionner le code, puis corrigez-le.

3. Toutes les lignes de code n'ont pas besoin d'être testées.

Chapitre 17 : Odeurs et heuristiques

1. Un code propre n'est pas un ensemble de règles, mais plutôt un système de valeurs qui déterminent la qualité de votre travail.

[Dans ce chapitre, Oncle Bob répertorie 66 autres variantes de son code et de ses heuristiques, dont beaucoup ont été couvertes dans le reste du livre. Les reproduire ici reviendrait essentiellement à copier et coller le nom de chaque élément, je me suis donc abstenu de le faire. Je vous suggère plutôt de lire le livre !]

Conclusion

Terminons là où nous avons commencé : Clean Code de Robert C. Martin est le livre de programmation le plus recommandé de tous les temps. Il y a une bonne raison à cela.