Nommages : réduire sa charge cognitive

Apéro PHP 18/04/2023

SAFTI ça le fait !

Fred Blanc
github.com/blanc-frederic

Lead dev chez SAFTI

En moyenne, 58% du temps pour compréhension du code

Xia and al. TSE.2017.2734091

Deux activités différentes

  • Résolution de problèmes ⇒ mathématiques
  • Compréhension du code ⇒ linguistique

... et pas valorisées à la même hauteur

Il faudrait refacto ces classes... bah on va tout cramer et refaire

Compréhension du code

Aider la mémoire court terme

  1. Structurer son code selon les standards
  2. Conventions (PSR-12 !)
  3. Bien choisir repères (commentaires, noms)
  4. Supprimer pollution (code mort ou commenté, fautes, décors, ...)

Aider la mémoire de travail

  1. Découper
  2. Activer mémoire long-terme
  3. Eviter d'empiler
  4. Renommer dès l'analyse

Aider la mémoire long terme

  1. Exercices sur design pattern (un par un !)
  2. Ecrire des docs
  3. Lire du code (open source)
  4. Développer :)

Astuce bonus

dormir

Obstacles à la compréhension

  1. (No comments or insufficient comments)
  2. Meaningless classes / methods / variables names
  3. Large number of lines of code in a class / method
  4. Unconsistent coding styles
  5. Navigating inheritance hierarchies

Xia and al. TSE.2017.2734091

Nommages : à ne pas faire

  • Pas d'humour
  • Pas de mystère
  • Pas d'abbréviation (sauf connues de tous)
  • Pas de négation (ex: $notEmpty)

Nommages : à faire

  • En anglais (comme PHP)
  • Noms prononçables
  • Donner des indices (Design Pattern, utilité, ...)
  • Utiliser des termes issus du métier

Conventions selon type

  • Classes, Propriétés, Variables ⇒ noms
  • Méthodes, Fonctions ⇒ verbe infinitif
  • Evènement ⇒ participe passé (ex: OrderValidated)
  • Valeurs d'Enum ⇒ adjectif ou nom
  • Booléens ⇒ préfixe (ex: isActive ou hasChildren)

Méthodes / fonctions

  • Maxi 5 arguments
  • Arguments aident pour les renseigner (ex: add(int $seconds))
  • Préfixe portant du sens :
    • getXxx : un seul élément, exception si non trouvé
    • findByXxx : array

Longueur : public = nom court, private = nom long

Variables

  • Maxi 4 mots
  • Porter du sens (ex: $user1, $user2 ⇒ $sender, $receiver)
  • Pas de notation hongroise (ex: $iMax, $strNom)

Longueur : portée grande = nom long, portée courte = nom court

Aider les autres

API, message broker, exports, ... :

Communiquer sur des noms neutres

Merci !

Des questions ?

Sources

  • Clean code - Robert C. Martin
  • The programmer's brain - Felienne Hermans