Konwencja nazewnictwa klas narzędzi w Javie

115

Jakich dobrych wskazówek należy przestrzegać podczas pisania klas narzędzi w języku Java?

Czy pakiety powinny być typu „util” czy „utils”? Czy jest to ClassUtil czy ClassUtils? Kiedy klasa jest „Pomocnikiem” lub „Narzędziem”? Narzędzie czy narzędzia? Czy używasz ich mieszanki?

Standardowa biblioteka Java używa zarówno narzędzi, jak i narzędzi:

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

Apache używa różnych narzędzi i programów narzędziowych, chociaż głównie programy narzędziowe:

  • 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 używa wielu klas pomocniczych i narzędzi:

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

Jak więc nazwać swoje klasy użyteczności?

java naming-conventions JR.
źródło

Odpowiedzi:

82

Podobnie jak w przypadku wielu takich konwencji, ważne jest nie tyle to, jakiej konwencji używasz, ile jej konsekwentnie. Na przykład, jeśli masz trzy klasy narzędzi i nazywasz je CustomerUtil, ProductUtils i StoreUtility, inne osoby próbujące korzystać z twoich klas będą ciągle zdezorientowane i przez pomyłkę wpiszą CustomerUtils, będą musiały to sprawdzić, przekląć kilka razy, itd. (Słyszałem kiedyś wykład na temat spójności, w którym prelegent umieścił slajd przedstawiający zarys jego przemówienia z trzema głównymi punktami, oznaczonymi jako „1”, „2” i „C”).

Nigdy, przenigdy nie twórz dwóch nazw różniących się tylko subtelnością pisowni, takich jak CustomerUtil i CustomerUtility. Jeśli istniał dobry powód, aby utworzyć dwie klasy, to musi być w nich coś innego, a nazwa powinna przynajmniej dać nam wskazówkę, na czym ta różnica polega. Jeśli jedna zawiera funkcje narzędziowe związane z nazwą i adresem, a druga zawiera funkcje narzędziowe związane z zamówieniami, nazwij je CustomerNameAndAddressUtil i CustomerOrderUtil lub takie. Regularnie wariuję, gdy widzę bezsensowne, subtelne różnice w nazwach. Tak jak wczoraj pracowałem nad programem, który miał trzy pola dla kosztów transportu, nazwane „fracht”, „koszt frachtu” i „frght”. Musiałem przestudiować kod, aby dowiedzieć się, jaka jest różnica między nimi.

Sójka
źródło
9
I IV dla numeru 4 :-) - Ale jaka była różnica między frachtem , kosztem frachtu i frght ?
KajMagnus
4
@KayMagnus Ten post był ponad rok temu, ale jak pamiętam, jednym z nich był aktualny koszt frachtu zapisany przed zmianą treści zamówienia, a tym samym potencjalnie koszt transportu; innym był standardowy koszt frachtu pobrany z tabeli; a trzecia to obliczony koszt stosowany w niektórych szczególnych przypadkach, takich jak przesyłki zagraniczne. Na przykład, dlaczego nie mogli przynajmniej zadzwonić do nich, powiedzmy „currFreight”, „stdFreight” i „calcFreight”. To przynajmniej dałoby wskazówkę.
Jay
Okay, dzięki za wyjaśnienie :-) Myślę, że
ciekawy
31

W świecie Java nie ma na to żadnej standardowej reguły / konwencji. Jednak wolę dodać „s” na końcu nazwy klasy, o czym wspominał @colinD.

Wydaje się to dość standardowe w stosunku do tego, co robi Mistrz Java API Designer Josh Bloch (kolekcja java, a także kolekcja Google)

Tak długo, jak Helper i Util będą działać, będę nazywać coś Pomocnikiem, gdy będzie miał API, które pomagają osiągnąć określoną funkcjonalność pakietu (biorąc pod uwagę pakiet jako implementację modułu); oznacza to, że narzędzie można wywołać w dowolnym kontekście.

Na przykład w aplikacji związanej z kontami bankowymi wszystkie statyczne interfejsy API specyficzne dla danego numeru będą trafiać do org.mycompany.util.Numbers

Wszystkie reguły biznesowe specyficzne dla konta, pomagające interfejsom API, trafiłyby do

org.mycompany.account.AccountHelper

W końcu chodzi o zapewnienie lepszej dokumentacji i czystszego kodu.

posiadacz pierścienia
źródło
5
Wydaje się rozsądne, że Helper byłby bardziej szczegółowy niż Utils.
KajMagnus
1
Tak, podoba mi się to podejście, jest bardziej logiczne.
Conan
3
Link jest uszkodzony. Znalazłem innego .
Chavjoh,
22

Podoba mi się konwencja dodawania „s” do nazwy typu, gdy typ jest interfejsem lub klasą, której nie kontrolujesz. Przykłady tego w JDK obejmują Collectionsi Executors. Jest to również konwencja używana w Google Collections.

Kiedy masz do czynienia z klasą , nad którą masz kontrolę, powiedziałbym, że ogólnie metody narzędziowe należą do samej klasy.

ColinD
źródło
2
Google Guava również używa tego wzorca
Jherico
11

Myślę, że „utils” powinno być nazwą pakietu. Nazwy klas powinny określać przeznaczenie logiki w nich zawartej. Dodawanie sufiksu -util (s) jest zbędne.

Aito
źródło
2
Nie byłoby to właściwe w podejściu „pakiet według funkcji” .
jpangamarca
1
@jpangamarca Artykuł, do którego utworzyłeś łącze, zawiera jednak pakiet „util” w przykładzie „pakiet według funkcji”. Myślę, że w praktyce często nie można uniknąć pewnych funkcji / warstw użytkowych.
kapex
1
@kapex Wydaje mi się, że przeoczenie ze strony autora. tld.organization.app.utilPakiet nie powinien istnieć (może, ale nie powinien), dowolną ilość tld.organization.app.feature.utilpakietów są perfekcyjnie.
jpangamarca
3

Jestem całkiem pewien, że słowa „pomocnicy” i „narzędzia” są używane zamiennie. W każdym razie, sądząc po podanych przez Ciebie przykładach, powiedziałbym, że jeśli nazwa Twojej klasy jest skrótem (lub zawiera skróty, takie jak „DomUtil”), a następnie nazwij swój pakiet „cokolwiek. ). W przeciwnym razie, jeśli ma pełną nazwę zamiast skrótu, nazwij ją „cokolwiek. CokolwiekNarzędzia”.

To naprawdę zależy od ciebie, ale dopóki programiści wiedzą, o czym mówisz, jesteś gotowy. Jeśli jednak robisz to profesjonalnie, jako praca dla kogoś, zapytaj go, jakie są standardy kodowania, zanim skorzystasz z mojej rady. Zawsze postępuj zgodnie ze standardami sklepu, bez względu na wszystko, ponieważ pomoże Ci to utrzymać pracę. :-)

KSwift87
źródło