Clean Code

Publié le 18/01/2020

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.