Convention de dénomination des classes d'utilitaires en Java

115

Lors de l'écriture de classes utilitaires en Java, quelles sont les bonnes directives à suivre?

Les paquets doivent-ils être "util" ou "utils"? Est-ce ClassUtil ou ClassUtils? Quand une classe est-elle un «assistant» ou un «utilitaire»? Utilitaire ou utilitaires? Ou utilisez-vous un mélange d'entre eux?

La bibliothèque Java standard utilise à la fois des utilitaires et des utilitaires:

  • javax.swing.Utilities
  • javax.print.attribute.AttributeSetUtilities
  • javax.swing.plaf.basic.BasicGraphicsUtils

Apache utilise une variété d'Util et Utils, bien que principalement Utils:

  • org.apache.commons.modeler.util.DomUtil
  • org.apache.commons.modeler.util.IntrospectionUtils
  • org.apache.commons.io.FileSystemUtils
  • org.apache.lucene.wordnet.AnalyzerUtil
  • org.apache.lucene.util.ArrayUtil
  • org.apache.lucene.xmlparser.DOMUtils

Spring utilise de nombreuses classes Helper et Utils:

  • org.springframework.web.util.UrlPathHelper
  • org.springframework.core.ReflectiveVisitorHelper
  • org.springframework.core.NestedExceptionUtils
  • org.springframework.util.NumberUtils

Alors, comment nommez-vous vos classes d'utilité?

java naming-conventions JR.
la source

Réponses:

82

Comme beaucoup de ces conventions, ce qui importe n'est pas tant la convention que vous utilisez, mais plutôt de l'utiliser de manière cohérente. Par exemple, si vous avez trois classes d'utilitaires et que vous les appelez CustomerUtil, ProductUtils et StoreUtility, les autres personnes qui essaient d'utiliser vos classes vont constamment se confondre et taper CustomerUtils par erreur, doivent le rechercher, vous maudire plusieurs fois, etc. (J'ai entendu une conférence sur la cohérence une fois où l'orateur a placé une diapositive montrant un aperçu de son discours avec trois points principaux, étiquetés «1», «2e» et «C».)

Ne faites jamais jamais deux noms qui ne diffèrent que par une certaine subtilité d'orthographe, comme avoir un CustomerUtil et un CustomerUtility. S'il y avait une bonne raison de créer deux classes, alors il devait y avoir quelque chose de différent à leur sujet, et le nom devrait au moins nous donner une idée de cette différence. Si l'un contient des fonctions utilitaires liées au nom et à l'adresse et l'autre contient des fonctions utilitaires liées aux commandes, appelez-les CustomerNameAndAddressUtil et CustomerOrderUtil ou quelque chose du genre. Je deviens régulièrement fou quand je vois des différences subtiles insignifiantes dans les noms. Comme hier, je travaillais sur un programme qui comportait trois champs pour les coûts de fret, appelés «fret», «coût du fret» et «frght». J'ai dû étudier le code pour comprendre quelle était la différence entre eux.

Geai
la source
9
Et IV pour le numéro 4 :-) - Mais quelle était la différence entre le fret , le coût du fret et le fright ?
KajMagnus
4
@KayMagnus Ce message remonte à plus d'un an, mais si je me souviens bien, l'un d'entre eux était le coût actuel du fret inscrit au dossier, avant de modifier le contenu de la commande et donc potentiellement le coût du fret; un autre était le coût du fret standard tiré d'une table; et le troisième était un coût calculé utilisé dans certains cas particuliers, comme les expéditions outre-mer. Par exemple, pourquoi ne pourraient-ils pas au moins les avoir appelés, disons "currFreight", "stdFreight" et "calcFreight". Cela aurait au moins donné une idée.
Jay
D'accord, merci pour l'explication :-) Un exemple de code étrange intéressant, je pense
KajMagnus
31

Il n'y a pas de règle / convention standard dans le monde Java pour cela. Cependant, je préfère ajouter "s" à la fin du nom de la classe comme @colinD l'a mentionné.

Cela semble assez standard par rapport à ce que fait Josh Bloch, le concepteur de l'API Java Master (collection java ainsi que collection google)

Tant que Helper et Util disparaissent, j'appellerai quelque chose un Helper quand il a des API qui aident à atteindre une fonctionnalité spécifique d'un package (en considérant un package comme pour implémenter un module); signifie alors qu'un Util peut être appelé dans n'importe quel contexte.

Par exemple, dans une application liée aux comptes bancaires, toutes les API statiques d'utilité spécifiques à un numéro iraient à org.mycompany.util.Numbers

Toutes les règles métier spécifiques au "Compte" aidant les API seraient envoyées à

org.mycompany.account.AccountHelper

Après tout, il s'agit de fournir une meilleure documentation et un code plus propre.

porteur de l'anneau
la source
5
Cela semble raisonnable, cet Helper serait plus précis que Utils.
KajMagnus
1
Oui, j'aime cette approche, c'est plus logique.
Conan
3
Le lien est rompu. J'en ai trouvé un autre .
Chavjoh le
22

J'aime la convention d'ajouter simplement "s" au nom du type lorsque le type est une interface ou une classe que vous ne contrôlez pas. Des exemples de cela dans le JDK incluent Collectionset Executors. C'est aussi la convention utilisée dans les collections Google.

Lorsque vous avez affaire à une classe sur laquelle vous avez un contrôle, je dirais que les méthodes utilitaires appartiennent généralement à la classe elle-même.

ColinD
la source
2
Google Guava utilise également ce modèle
Jherico
11

Je pense que «utils» devrait être le nom du paquet. Les noms de classe doivent spécifier le but de la logique à l'intérieur. L'ajout du ou des suffixes -util (s) est redondant.

Aito
la source
2
Ce ne serait pas la bonne chose à faire dans une approche «package par fonctionnalité» .
jpangamarca
1
@jpangamarca L'article que vous avez lié a un package "util" dans l'exemple pour "package by feature". Je pense qu'en pratique, une sorte de fonctionnalité / couche utilitaire ne peut souvent pas être évitée.
kapex
1
@kapex Un oubli de l'auteur, je suppose. Un tld.organization.app.utilpaquet ne devrait pas exister (pourrait, mais ne devrait pas), n'importe quel nombre de tld.organization.app.feature.utilpaquets convient parfaitement.
jpangamarca le
3

Je suis à peu près sûr que les mots «helpers» et «utilities» sont utilisés de manière interchangeable. Quoi qu'il en soit, à en juger par les exemples que vous avez fournis, je dirais que si votre nom de classe est une abréviation (ou contient des abréviations telles que "DomUtil"), appelez votre package "whatthing.WhateverUtil" (ou Utils s'il y a plus d'un utilitaire dans votre package ). Sinon, s'il a un nom complet au lieu d'une abréviation, alors appelez-le "peu importe.

Cela dépend vraiment de vous, mais tant que les codeurs savent de quoi vous parlez, vous êtes prêt à partir. Si vous faites cela professionnellement en tant que travail pour quelqu'un, demandez-lui quelles sont ses normes de codage avant de suivre mon conseil. Suivez toujours les normes de l'atelier, quoi qu'il en soit, car cela vous aidera à conserver votre emploi. :-)

KSwift87
la source