« Clean Code » résumé en quelques lignes

Ce texte est une traduction et une adaptation de Summary of 'Clean code' by Robert C. Martin.

Voici un résumé des principales idées du livre « Clean Code: A Handbook of Agile Software Craftsmanship » de Robert C. Martin (Uncle Bob).

Du code est propre (clean) si il peut être compris facilement - par chaque personne de l'équipe. Un code propre (Clean code) 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é et la maintenabilité.

Une goutte d'eau

Règles générales

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

Règles de design

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

Astuces pour la compréhensibilité

  1. 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.
  2. Utilisez des noms de variables explicites.
  3. Encapsulez les conditions limites : elles sont compliquées à suivre. Il vaut mieux les isoler à un endroit.
  4. Préférez des value objects spécifiques plutôt que des types primitifs
  5. Évitez les dépendances logiques : n'écrivez pas de méthodes qui dépendent d'autre chose dans la même classe.
  6. Évitez les conditions négatives.

Règles de nommages

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

Règles relatives aux fonctions

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

Règles relatives aux commentaires

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

Structure du code source

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

Objets et structures de données

  1. Cachez les structures internes.
  2. Devraient être petits.
  3. Ne font qu'une chose.
  4. 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.
  5. Une classe de base ne devrait rien connaître de ses classes dérivées.
  6. Il vaut mieux avoir plusieurs fonctions que de passer du code à une fonction pour qu'elle choisisse un comportement.
  7. Préférez des méthodes non statiques.

Tests

  1. Un concept par test.
  2. Rapides.
  3. Indépendants.
  4. Répétables.
  5. Auto validants.
  6. Utiles.
  7. Lisibles.
  8. Faciles à lancer.
  9. Utilisez un outil de génération de couverture de code.

Indicateurs d'un code pas terrible (Code smells)

  1. Rigidité : le logiciel est difficile à faire évoluer. Une petite modification peut causer une cascade de changements.
  2. Fragilité : le logiciel dysfonctionnement en plusieurs endroits en réponse à un unique changement.
  3. 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.
  4. Complexité inutile.
  5. Répétition inutile.
  6. Opacité : le code est difficile à comprendre.

Gestion des erreurs

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