Соглашение об именах для служебных классов в Java

116

Какие полезные рекомендации следует соблюдать при написании служебных классов на Java?

Должны быть пакеты "util" или "utils"? Это ClassUtil или ClassUtils? Когда класс является «Помощником» или «Полезностью»? Утилиты или утилиты? Или вы используете их смесь?

Стандартная библиотека Java использует как утилиты, так и утилиты:

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

Apache использует различные утилиты и утилиты, но в основном утилиты:

  • 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 использует множество классов Helper и Utils:

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

Итак, как вы называете свои служебные классы?

java naming-conventions JR.
источник

Ответы:

83

Как и во многих подобных соглашениях, важно не столько то, какое соглашение вы используете, сколько то, что вы используете его последовательно. Например, если у вас есть три служебных класса и вы называете их CustomerUtil, ProductUtils и StoreUtility, другие люди, пытающиеся использовать ваши классы, будут постоянно запутываться и вводить CustomerUtils по ошибке, должны искать его, проклинать вас несколько раз, и т. д. (Однажды я слышал лекцию о последовательности, где докладчик показывал слайд, показывающий план своей речи с тремя основными пунктами, отмеченными «1», «2-й» и «C».)

Никогда никогда не создавайте два имени, которые отличаются только тонкостью написания, например, наличие CustomerUtil и CustomerUtility. Если была веская причина для создания двух классов, значит, в них должно быть что-то другое, и название должно, по крайней мере, дать нам представление, в чем это различие. Если одна из них содержит служебные функции, связанные с именем и адресом, а другая - служебные функции, связанные с заказами, назовите их CustomerNameAndAddressUtil и CustomerOrderUtil или что-то в этом роде. Я регулярно схожу с ума, когда вижу бессмысленные тонкие различия в именах. Как и вчера, я работал над программой, в которой были три поля для транспортных расходов: «фрахт», «фрахт» и «фрахт». Мне пришлось изучить код, чтобы понять, в чем разница между ними.

Джей
источник
9
И IV за номером 4 :-) - Но что было различие между грузовым , freightcost и frght ?
KajMagnus
4
@KayMagnus Этот пост был больше года назад, но, насколько я помню, одним из них была текущая стоимость перевозки в записи до изменения содержимого заказа и, следовательно, потенциально стоимости перевозки; другой - стандартная стоимость перевозки, взятая из таблицы; и третья - это расчетная стоимость, используемая в некоторых особых случаях, например, при отправке за границу. Например, почему они не могли хотя бы назвать их, скажем, «currFreight», «stdFreight» и «calcFreight». Это по крайней мере дало бы ключ к разгадке.
Джей
Хорошо, спасибо за объяснение :-) Я думаю, интересный пример странного кода
KajMagnus
31

В мире Java для этого нет стандартных правил / соглашений. Однако я предпочитаю добавлять «s» в конце имени класса, как упоминал @colinD.

Это кажется довольно стандартным для того, что делает Мастер java API Designer Джош Блох (коллекция java, а также коллекция google)

Пока идут Helper и Util, я буду называть что-то Helper, если у него есть API, которые помогают достичь определенной функциональности пакета (учитывая, что пакет реализует модуль); означает, что Util можно вызывать в любом контексте.

Например, в приложении, связанном с банковскими счетами, все статические API-интерфейсы служебных программ для конкретных номеров будут идти в org.mycompany.util.Numbers

Все бизнес-правила для конкретных бизнес-правил, помогающие API, перейдут в

org.mycompany.account.AccountHelper

В конце концов, это вопрос обеспечения лучшей документации и более чистого кода.

кольцо предъявитель
источник
5
Кажется разумным, что Helper будет более конкретным, чем Utils.
KajMagnus
1
Да, мне нравится такой подход, он более логичный.
Conan
3
Ссылка не работает. Я нашел еще один .
Chavjoh
22

Мне нравится соглашение о простом добавлении «s» к имени типа, когда тип является интерфейсом или классом, которым вы не управляете. Примеры этого в JDK включают Collectionsи Executors. Это также соглашение, используемое в Коллекциях Google.

Когда вы имеете дело с контролируемым вами классом , я бы сказал, что служебные методы в целом принадлежат самому классу.

ColinD
источник
2
Google Guava также использует этот шаблон
Jherico
11

Я думаю, что в названии пакета должно быть «utils». Имена классов должны указывать цель логики внутри него. Добавление суфикса -util (s) излишне.

Aito
источник
2
Это было бы неправильным поступком в рамках подхода «пакет за функцией» .
jpangamarca
1
@jpangamarca В статье, которую вы связали, есть пакет "util" в примере для "пакет по функции". Я думаю, что на практике какой-то утилитарной функции / уровня часто не избежать.
kapex
1
@kapex Оплошность автора, наверное. tld.organization.app.utilПакет не должен существовать (может, но не должен), любое количество tld.organization.app.feature.utilупаковок прекрасно.
jpangamarca
3

Я почти уверен, что слова «помощники» и «утилиты» взаимозаменяемы. В любом случае, судя по приведенным вами примерам, я бы сказал, что если ваше имя класса является аббревиатурой (или в нем есть аббревиатуры, такие как "DomUtil"), тогда назовите ваш пакет "something.WhateverUtil" (или Utils, если в вашем пакете более одной утилиты ). В противном случае, если у него есть полное имя вместо аббревиатуры, назовите его «something.WhateverUtilities».

Это действительно зависит от вас, но пока программисты знают, о чем вы говорите, вы готовы к работе. Если вы делаете это профессионально как работу для кого-то, спросите их, каковы их стандарты кодирования, прежде чем принимать мой совет. Всегда соблюдайте стандарты магазина, несмотря ни на что, так как это поможет вам сохранить работу. :-)

KSwift87
источник