Bien nommer les classes et les méthodes d’une API

Pour les classes, cela DOIT être facile...

Nommer une classe est normalement simple : il suffit de choisir un terme suffisamment général et décrivant le mieux la notion gérée par cette classe. Si la classe est bien conçue, et qu’elle respecte le principe de responsabilité unique, la nommer ne devrait pas présenter de difficultés.
Si lui trouver un petit nom s’avère difficile, ou qu’aucun nom ne paraît raisonnablement satisfaisant, il est probable que cette classe fasse trop de choses. Il n’y a alors qu’une seule chose à faire : la tronçonner ! Une autre astuce est de s’imposer de commenter la classe en une seule phrase. Si cette phrase est impossible à écrire, ou si elle n’a rien à voir avec le nom choisi, il faut changer le nom, ou bien découper la classe.

... c’est pour les méthodes que ça se complique !

Nommer correctement les méthodes publiques d’une classe a son importance. Récemment, j’ai dû enrichir les API d’un de nos logiciels. Celles-ci sont destinées à des développeurs tiers qui éventuellement ne font pas partie de notre société. Pas question donc de laisser des ambigüités ou des incohérences. Et lorsque on est en présence d’un package contenant des dizaines de classes, et que chacune d’entre elles comprend une ou plusieurs dizaines de méthodes, on se retrouve donc à fournir plusieurs centaines de méthodes, et quelques règles s’imposent :

Utiliser l’anglais : ne connaissant pas à priori quelle sera la nationalité des développeurs qui utiliseront l’API, il faut s’imposer la langue internationale de l’informatique : l’anglais.

Débuter les noms par un verbe indiquant aussi précisément que possible le type d’action réalisée :
    countUsers() : compte le nombre d’utilisateurs
    isExpired() : indique si le compte-utilisateur est expiré

Combiner des mots entiers jusqu’à décrire l’action réalisée par la méthode. 
    getExpirationDate() : retourne la date d’expiration
    notifyAllClients() : notifie tous les clients

Eviter les informations inutiles : éviter de faire porter au nom de la méthode une information non indispensable, ou bien disponible ailleurs.
Ex : si une méthode renvoie tous les employés d’un service, et qu’elle s’applique soit sur un objet Service, soit qu’elle prend un objet Service en paramètre, il est inutile de l’appeler getEmployeesByService ; getEmployees est suffisant.

Ne pas pas utiliser le mot « And » : si le recours au mot « And » est requis, c’est que la méthode à nommer réalise plusieurs actions. Dans ce cas, il faut la tronçonner. En effet, le principe de responsabilité unique s’applique à tous les niveaux, y compris au niveau d’une méthode.

Conserver la même logique dans toute l’API : ce qui est important, ce n’est pas de se faire des nœuds au cerveau pour savoir si une méthode qui met à jour un objet métier doit commencer par update ou modify. En revanche, ce qui est important, c’est de faire un choix, et de l'appliquer à travers toute l'API.

Bien-sûr, ces quelques règles ne font pas le travail à la place des développeurs, et elles peuvent être complétées. Mais les respecter m’a permis de produire une API cohérente ce qui au final facilite le travail des utilisateurs.