9 Directives pour Créer des Noms Expressifs

Le nommage est subjectif et situationnel, c’est un art, et comme pour la plupart des arts, nous découvrons des modèles. J’ai beaucoup appris en lisant le code d’autres personnes. Dans cet article, j’ai compilé 9 directives que j’aurais aimé que d’autres aient suivies quand j’ai lu leur code.

Quand un ingénieur logiciel ouvre une classe, elle devrait connaître, basé sur les noms, les responsabilités de la classe. Oui, je sais que le nommage n’est qu’un rayon de la roue, les structures physiques et logiques jouent aussi un rôle significatif dans la compréhension du code, tout comme la complexité. Dans cet article, je me concentre uniquement sur le nommage parce que je pense que c’est l’impact le plus significatif sur la compréhension du code.

N’Incluez pas le Type Sauf s’il Clarifie l’Intention

Un type peut être n’importe quoi, d’un type de programmation (string, int, decimal) à un regroupement de responsabilités (Util, Helper, Validator, Event, etc.). Souvent c’est une classification qui n’exprime pas l’intention.

Regardons un exemple : Le nom StringHelper n’exprime pas grand-chose. Une string est un type système, et Helper est vague, StringHelper parle plus du “comment” que de l’intention. Si à la place, nous changeons le nom en DisplayNameFormatter nous obtenons une image plus claire de l’intention. DisplayName est très spécifique, et Formatter exprime le résultat. Formatter peut ou peut ne pas être un type, mais cela n’a pas d’importance, parce qu’il exprime l’intention.

Il y a toujours des exceptions ; par exemple, dans ASP.Net MVC, les contrôleurs doivent se terminer par “Controller” ou l’application ne fonctionne pas. En utilisant des paradigmes tels que Domain Driven Design (DDD), des noms comme “Services,” “Repository,” “ValueType” et “Model” ont une signification en DDD et expriment la responsabilité.

Par exemple, UserRespository implique que les données utilisateur sont récupérées et sauvegardées dans un magasin de données.

Évitez les Métaphores

Les métaphores sont culturelles, et les ingénieurs d’autres cultures pourraient ne pas comprendre l’intention.

Métaphores communes aux États-Unis :

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

Métaphores communes en Nouvelle-Zélande :

• Spit the dummy
• Knackered
• Hard yakka

Utilisez des Verbes

Steve Yegge a écrit un article de blog (très long) sur l’utilisation de verbes plutôt que de noms.

Son point est d’utiliser des verbes, les applications sont composées de noms, mais les noms ne font pas de choses. Les systèmes sont inutiles avec seulement des noms, exprimez plutôt l’action dans les noms des méthodes.

Par exemple, UserAuthentication*(nom).AuthenticateUser(action/verbe)* exprime l’action de vérifier les identifiants d’un utilisateur.

Soyez Descriptif

Soyez descriptif, plus il y a de détails, mieux c’est — exprimez la responsabilité dans le nom.

Demandez-vous, quelle est la seule chose que cette classe ou fonction fait bien ?

Si vous avez des difficultés à trouver un nom, la classe ou fonction pourrait avoir plus d’une responsabilité et ainsi violer le Principe de Responsabilité Unique.

Ne Vous Appuyez pas sur les Commentaires pour l’Intention

Les commentaires sont un excellent moyen de fournir un contexte supplémentaire au code mais ne vous appuyez pas sur les commentaires. Les noms des classes et méthodes devraient se suffire à eux-mêmes.

Dans Refactoring: Improving the Design of Existing Code par Martin Fowler, Kent Beck, John Brant, William Opdyke, et Don Roberts :

… les commentaires sont souvent utilisés comme un déodorant. Il est surprenant de voir combien de fois vous regardez du code fortement commenté et remarquez que les commentaires sont là parce que le code est mauvais.

Une autre citation merveilleuse des auteurs de “In Refactoring” :

Quand vous ressentez le besoin d’écrire un commentaire, essayez d’abord de refactoriser le code pour que tout commentaire devienne superflu. Page 88

Plusieurs fois quand le code est refactorisé et encapsulé dans une méthode, vous trouverez d’autres endroits où il est possible d’exploiter la nouvelle méthode, des endroits où vous n’aviez jamais anticipé utiliser la nouvelle méthode.

Parfois quand on appelle une méthode, le consommateur a besoin de savoir quelque chose de particulier sur la méthode, si cette particularité fait partie du nom, alors le consommateur n’a pas besoin de réviser le code source.

Voici un exemple d’incorporation d’un commentaire dans un nom.

Avec commentaires :

// without tracking
var user = GetUserByUserId(userId);

Refactorisé pour inclure le commentaire dans le nom de la méthode :

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

D’autres ingénieurs savent maintenant que cette méthode n’a pas de suivi avant qu’ils n’aient besoin de lire le code source ou de trouver le commentaire.

Les commentaires devraient être votre dernière ligne de défense quand c’est possible, penchez-vous vers d’autres moyens d’exprimer l’intention incluant l’utilisation de structure physique et logique et de noms pour transmettre l’intention.

Abstenez-vous d’Utiliser des Noms avec une Signification Ambiguë

Évitez les noms avec des significations ambiguës. La signification des noms ambigus change de projet en projet ce qui rend la compréhension de l’intention plus difficile pour un nouvel ingénieur.

Voici une liste de noms ambigus communs :

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Utilisez le Même Langage que le Domaine Métier

Utilisez la même terminologie dans le code que dans le domaine métier. Cela permet aux ingénieurs et aux experts du domaine (SME) de communiquer facilement les idées parce qu’ils partagent le même vocabulaire. Quand il n’y a pas de vocabulaire partagé, des traductions se produisent qui mènent invariablement à des malentendus.

Dans un projet sur lequel j’ai travaillé, l’entreprise a commencé avec “Pupil” puis est passée à “Student.” Les ingénieurs logiciels n’ont jamais mis à jour le logiciel pour refléter le changement de terminologie. Quand de nouveaux ingénieurs ont rejoint le projet, la plupart croyaient que Pupil et Student étaient des concepts différents.

Utilisez le Jargon de l’Industrie

Quand c’est possible, utilisez une terminologie qui a une signification à travers l’industrie logicielle.

La plupart des ingénieurs logiciels, quand ils voient quelque chose nommé “factory,” pensent immédiatement au pattern factory.

Utiliser des paradigmes d’application existants tels que “Clean Architecture” et “Domain Driven Design” facilite le partage d’idées et crée un langage commun pour que les ingénieurs communiquent des idées entre eux.

Le pire nommage possible est de coopter une terminologie à l’échelle de l’industrie et de lui donner une signification différente.

Quand Vous Nommez des Booléens…

Les noms de booléens devraient toujours être une réponse à une question avec sa valeur soit vraie soit fausse.

Par exemple, isUserAutheticated, la réponse est soit oui (true) soit non (false)

Utilisez des mots comme :

• Has
• Does
• Is
• Can

Évitez les noms négatifs, par exemple :

Un nom de variable négatif :

var IsNotDeleted = true; // this is confusing

if(!IsNotDeleted) { // it gets even more confusing when the value is negated
  //Do magic
}

Sans nom de variable négatif :

var IsDeleted = true; // this is confusing

if(!IsDeleted) { 
  //Do magic
}

En Conclusion

Choisir des noms expressifs est crucial pour communiquer l’intention, la conception, et la connaissance du domaine au prochain ingénieur. Souvent nous travaillons sur du code pour corriger des défauts ou incorporer de nouvelles fonctionnalités, et nous compilons continuellement du code dans notre tête en essayant de comprendre comment il fonctionne. Le nommage nous donne des indices sur ce que l’ingénieur précédent pensait, sans cette communication entre les ingénieurs passés et futurs nous nous handicapons dans la croissance de l’application. Condamnant potentiellement le projet à l’échec.