9 Directives pour Créer des Noms Expressifs

La dénomination est subjective et situationnelle, 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 souhaité que d’autres aient suivies quand j’ai lu leur code.

Quand un ingénieur logiciel ouvre une classe, il devrait savoir, en se basant sur les noms, quelles sont les responsabilités de la classe. Oui, je sais que la dénomination n’est qu’un élément de la roue, les structures physiques et logiques jouent également un rôle important dans la compréhension du code, tout comme la complexité. Dans cet article, je me concentre uniquement sur la dénomination car je pense que c’est l’impact le plus significatif sur la compréhension du code.

N’Incluez Pas le Type à Moins qu’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, car 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 dans DDD et expriment la responsabilité.

Par exemple, UserRepository implique que les données utilisateur sont récupérées et enregistré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 courantes aux États-Unis :

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

Métaphores courantes en Nouvelle-Zélande :

• Spit the dummy
• Knackered
• Hard yakka

Utilisez des Verbes

Steve Yegge a écrit un (très long) article de blog 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 rien. 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 de détails, c’est mieux — exprimez la responsabilité dans le nom.

Posez-vous la question : quelle est l’une des choses que cette classe ou fonction fait bien ?

Si vous avez du mal à trouver un nom, la classe ou la 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 y appuyez pas. Les noms des classes et des 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ésodorisant. C’est surprenant de voir à quel point souvent vous regardez du code densément commenté et remarquez que les commentaires sont là parce que le code est mauvais.

Une autre citation merveilleuse des auteurs de « Refactoring » :

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

Souvent, quand le code est refactorisé et encapsulé dans une méthode, vous découvrirez d’autres emplacements où il est possible de tirer parti de la nouvelle méthode, des endroits que vous n’aviez jamais anticipés pour utiliser la nouvelle méthode.

Parfois, lors de l’appel d’une méthode, le consommateur doit savoir quelque chose de particulier sur la méthode, si cette particularité fait partie du nom, alors le consommateur n’a pas besoin de consulter 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);

Les 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 possible, préférez d’autres façons d’exprimer l’intention, notamment en utilisant la structure physique et logique et les 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 d’un projet à l’autre, ce qui rend la compréhension de l’intention plus difficile pour un nouvel ingénieur.

Voici une liste de noms ambigus courants :

• 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 en la matière (SME) de communiquer facilement les idées car ils partagent le même vocabulaire. Quand il n’y a pas de vocabulaire partagé, la traduction se produit, ce qui inévitablement mène à 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 la Terminologie de l’Industrie

Quand possible, utilisez la terminologie qui a une signification dans l’industrie du logiciel.

La plupart des ingénieurs logiciels, quand ils voient quelque chose nommé « factory », pensent immédiatement au modèle factory.

L’utilisation de 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 les idées entre eux.

La pire dénomination possible est de s’approprier la terminologie largement utilisée dans l’industrie et de lui donner une signification différente.

Lors de la Dénomination de Booléens…

Les noms booléens devraient toujours être une réponse à une question avec sa valeur soit true soit false.

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

Utilisez des mots comme :

• Has
• Does
• Is
• Can

Évitez les noms niés, par exemple :

Un nom de variable nié :

var IsNotDeleted = true; // this is confusing

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

Sans nom de variable nié :

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 les connaissances 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. La dénomination 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. Potentiellement condamnant le projet à l’échec.