Java: правильное именование классов с акронимами

Быстрый ответ

В Java обычно аббревиатуры из двух букв пишутся заглавными буквами (HTTPError), а аббревиатуры из трех и более букв удобнее читать, если большую букву имеет только первая буква (XmlParser). Это поддерживает удобочитаемость кода и придерживается правил camelCase и PascalCase.

Примеры:

• HttpUrl вместо HTTPURL
• IoStream вместо IOSTREAM

Декларативность и удобство понимания

Предпочитайте аббревиатуры, которые легко понять. Допустим, XmlHttpRequest довольно известен, в то время как непонятные сокращения могут запутать. Используйте однозначные и общепринятые сокращения для улучшения самодокументирования кода.

Правила для аббревиатур из трех и более букв:

• UrlEncoder вместо URLEncoder
• TcpSession — оба варианта применимы: в верхнем регистре и смешанном.

Подробнее об этом расскажет наш спикер на видео

Понятность – главное

Удобочитаемость – наше все: выбирайте названия, которые делают код более понятным. SvgImage проще читать, чем SVGImage, поскольку оно соответствует привычному режиму чтения и письма. Это также упрощает взаимодействие с инструментами и библиотеками Java, использующими PascalCase и camelCase.

Единообразие — залог порядка

Следует придерживаться некой последовательности в именовании. Если вы используете TcpSession, следует избегать TCPSession в других частях кода. Единообразие в соглашении об именовании облегчает восприятие и поддержку кода.

Обучаемся на примерах библиотек

В качестве образца служат популярные Java-библиотеки, такие как JavaSE, Apache, Spring, которые могут установить основные направления для ваших собственных правил именования.

Визуализация

Можно сравнить принципы именования в Java с функцией Caps Lock на клавиатуре, которая определяет, когда использовать ЗАГЛАВНЫЕ буквы, а когда нет:

Обычная клавиатура:       [Caps Lock] -> [ВСЕ ЗАГЛАВНЫЕ]

Стиль именования в Java:   [Caps Lock] -> [Только Первые Буквы, Если Не Одна]

Исходя из этого, приведем примеры с аббревиатурами:

По умолчанию:  [URL]
Стандарт:      [URL]
В стиле Java:  [Url]

Если аббревиатура используется самостоятельно:

По умолчанию: [HTTP]
Стандарт:     [HTTP]
В стиле Java: [HTTP]

Функция Caps Lock в Java – это как воспитанный английский джентльмен: вежлив и уместен. Звучит знакомо, правда? 😄

Подбор подходящего идентификатора

При выборе идентификатора следуйте эти правилам:

• Ясно излагайте назначение кода
• Избегайте двусмысленных сокращений
• Обеспечивайте совместимость со стандартами и инструментами
• Пишите код таким образом, чтобы его было легко поддерживать

CamelCase для логики кода

Использование camel case (jsonValue) для именования переменных, классов и методов поможет вам сохранять единообразие кода в рамках устанавливаемых соглашений об именовании Java. В добавок, ваш код не будет выглядеть как "кричащий".

Именование экземпляров: важность единообразия

Давая имя экземпляру класса JsonParser, назовите его jsonParser, чтобы поддержать последовательность стиля кодирования.

Исключения из правил: когда и почему

Иногда применяются специфические имена, которые выходят за рамки общечинных правил. Например, из за согласованности с командой или обычных практик. Важно обсудить такие исключения и отразить их в документации. Правила созданы затем, чтобы умные люди имели руководство, а не следовали им слепо.

Полезные материалы

1. Code Conventions for the Java Programming Language: 9. Naming Conventions — официальные соглашения об именовании в Java от компании Oracle.
2. Google Java Style Guide — рекомендации Google по стилю написания кода и именованию в Java.
3. Newest 'java+naming-conventions' Questions – Stack Overflow — обсуждение и практические примеры использования соглашений об именовании в Java на Stack Overflow.
4. Camel case – Wikipedia — Wikipeсdia статья о соглашении использования CamelCase в Java.
5. Java Naming Conventions – HowToDoInJava — полное руководство с примерами по соглашениям именования в Java.
6. [Clean Code: A Handbook of Agile Software Craftsmanship [Book]](https://www.oreilly.com/library/view/clean-code-a/9780136083238/) — книга о написании качественного кода на Java с различными рекомендациями по именованию.