Clean Code

Le texte original se trouve ici. J’ai un peu sauté sur l’occasion de ne pas avoir à lire ce livre-ci, et profiter du résumé de quelqu’un d’autre 😊. J’ai adapté certains passages pour ma propre compréhension.

Il existe aussi une version Gist.

Du code est propre (clean) si il peut être compris facilement - par chaque personne de l’équipe. Un code propre peut être lu et amélioré par un·e développeur·se autre que la personne qui l’a écrit.

Avec la compréhensibilité vient:

• la lisibilité,
• la facilité à changer,
• l’extensibilité
• la maintenabilité.

Règles générales

• Suivez des conventions reconnues.
• Keep it simple stupid. Plus simple est toujours mieux. Réduisez la complexité autant que possible.
• Règle du boy scout : laissez le camp plus propre que l’état dans lequel vous l’avez trouvé.
• Lors de résolution d’un problème, toujours chercher et trouver la cause racine.
• Suivez le principe de moindre surprise.
• DRY : ne vous répétez pas, et mais attention à l’interprétation de ce principe.

Règles de design

• Gardez les données configurables (par exemple les constantes) à hauts niveaux. Elles devraient être faciles à changer.
• Préférez le polymorphisme aux if/else ou switch/case.
• Évitez la sur-configurabilité et tout ce qui n’a pas prouvé sa nécessité.
• Utilisez l’injection de dépendances.
• Suivez la loi de Déméter : une classe ne devrait connaître que ses dépendances directes.

Astuces pour la compréhensibilité

• Soyez cohérent. Si vous faites quelque chose d’une certaines manière, toutes les choses similaires devraient être faites de la même manière.
• Utilisez des noms de variables explicites.
• Encapsulez les conditions limites : elles sont compliquées à suivre. Il vaut mieux les isoler à un endroit.
• Préférez des value objects spécifiques plutôt que des types primitifs
• Évitez les dépendances logiques : n’écrivez pas de méthodes qui dépendent d’autre chose dans la même classe.
• Évitez les conditions négatives.

Règles de nommages

• Choisissez des noms descriptifs et sans ambiguïté.
• Faites des distinctions qui ont du sens.
• Utilisez des noms prononçables.
• Utilisez des noms cherchables.
• Remplacez les nombres magiques par des constantes bien nommées.
• Évitez d’ajouter des préfixes ou des informations sur les types.

Règles relatives aux fonctions

• Courtes.
• Ne fait qu’une chose et la fait bien.
• Utilisez des noms descriptifs.
• Préférez les avec le moins d’arguments possibles, idéalement pas plus de 3.
• Sans effets de bord.
• N’utilisez pas de flag : écrivez plutôt plusieurs méthodes sans ce type d’argument.

Règles relatives aux commentaires

• Essayez d’écrire du code expressif ne nécessitant pas de commentaire. Si c’est impossible, prenez le temps d’écrire un bon commentaire.
• Ne soyez pas redondant (par exemple : i++; // increment i).
• N’ajoutez pas de bruit évident.
• N’utilisez pas les commentaires de fermeture de bloc (par exemple : } // end of function).
• Ne commentez pas de code. Supprimez ce code.
• Utilisez des commentaires pour expliquer l’intention.
• Utilisez des commentaires pour avertir des conséquences.

Structure du code source

• Séparez les concepts verticalement.
• Le code lié devrait apparaître dense verticalement.
• Déclarez les variables à proximité de leurs usages.
• Les fonctions dépendantes les unes des autres devraient être à proximité.
• Les fonctions similaires devraient être à proximité les unes des autres.
• Placez les fonctions dans la direction descendante.
• Gardez les lignes courtes.
• N’alignez rien horizontalement.
• Utilisez des espaces pour associer des choses liées et dissocier des choses liées faiblement.
• Ne cassez pas l’indentation.

Objets et structures de données

• Cachez les structures internes.
• Devraient être petits.
• Ne font qu’une chose.
• Possèdent un petit nombre de variables d’instance. Si votre classe a trop de variables d’instance, il est probable que votre objet fasse plus qu’une chose.
• Une classe de base ne devrait rien connaître de ses classes dérivées.
• Il vaut mieux avoir plusieurs fonctions que de passer du code à une fonction pour qu’elle choisisse un comportement.
• Préférez des méthodes non statiques.

Tests

• Un concept par test.
• Rapides.
• Indépendants.
• Répétables.
• Auto validants.
• Utiles.
• Lisibles.
• Faciles à lancer.
• Utilisez un outil de génération de couverture de code.

Indicateurs d’un code pas terrible (Code smells)

• Rigidité : le logiciel est difficile à faire évoluer. Une petite modification peut causer une cascade de changements.
• Fragilité : le logiciel dysfonctionnement en plusieurs endroits en réponse à un unique changement.
• Immobilité : vous ne pouvez pas réutiliser une partie du code dans d’autres projets car cette opération est risquée ou nécessite un grand effort.
• Complexité inutile.
• Répétition inutile.
• Opacité : le code est difficile à comprendre.

Gestion des erreurs

• Ne mélangez pas la gestion des erreurs et le code.
• Utilisez des Exceptions au lieu de renvoyer des codes d’erreurs.
• Ne retournez pas null, n’utilisez pas null non plus.
• Lancer des exceptions avec du contexte.