Именование — пакеты, классы, методы, переменные, константы

Опирается на правила: JS-2.1 … JS-2.8 из Java Style Guide → раздел 2. Именование.

Важно знать

• Пакеты — нижний регистр, без _, единственное число (com.example.util, не utils).
• Классы — существительные (Car, не Running).
• Интерфейсы — существительные или -able (Runnable); не начинать с I.
• Аббревиатуры: 2 буквы CAPS (IOStream); 3+ только первая большая (XmlParser).
• Методы — глаголы (getName, expand, не name).
• Тесты: длинное говорящее имя или короткое + @DisplayName; snake_case запрещён.
• Переменные — camelCase, начинаются с lowercase.
• Константы — UPPER_SNAKE_CASE, обязательно static final.

Именование — это первая документация кода. Хорошее имя устраняет необходимость в комментариях (см. Комментарии). Плохое имя — даёт ложный сигнал, заставляет читать реализацию вместо сигнатуры. UCP опирается на стандартные Java-конвенции с парой добавок (запрет IInterface, конвенция для аббревиатур).

Пакеты

JS-2.1, JS-2.2: нижний регистр, единственное число.

package com.example.orderservice;       // ✓
package com.example.order_service;      // ✗ — подчёркивание
package com.example.OrderService;       // ✗ — camelCase

package java.util;                      // ✓ — стандарт
package com.example.util;               // ✓
package com.example.utils;              // ✗ — множественное число

Почему единственное число: следуем стандартному API. java.util, java.lang, java.time — все в единственном. Множественное в service-проектах создаёт inconsistency.

Классы

JS-2.3: существительные.

class Car {}                            // ✓
class Order {}                          // ✓
class PaymentProcessor {}               // ✓

class Running {}                        // ✗ — глагольная форма
class Calculate {}                      // ✗ — глагол

Класс — это сущность, не действие. Действие принадлежит методу класса.

Интерфейсы

JS-2.4: существительные или -able, без префикса I.

interface Runnable {}                   // ✓ — стандартная конвенция Java
interface Comparable {}                 // ✓
interface OrderRepository {}            // ✓ — существительное
interface OrderValidator {}             // ✓ — существительное (-er/-or формы)

interface IEnumerable {}                // ✗ — C#-конвенция, не Java
interface IOrderService {}              // ✗
interface AbstractOrder {}              // ✗ — путаница с abstract class

Java стандартная библиотека: Runnable, Callable, Iterable, Comparable, Closeable. UCP следует тому же паттерну.

Аббревиатуры

JS-2.5: правило по длине.

class IOStream {}                       // ✓ — 2 буквы CAPS
class IoStream {}                       // ✗
class IpAddress {}                      // ✗ (2 буквы)

class XmlParser {}                      // ✓ — 3 буквы, только первая CAPS
class XMLParser {}                      // ✗
class HtmlGenerator {}                  // ✓
class HTMLGenerator {}                  // ✗

class Pk2dfCertificate {}               // ✓ — 3+ букв, первая CAPS, цифра не считается
class C2CTariff {}                      // ✓ — 2 буквы C2C → CAPS, '2' не считается
class C2сTariff {}                      // ✗ — микс регистров

class HttpUrlConnection {}              // ✓ — каждая 3+-буквенная аббревиатура: Capitalize
class HTTPURLConnection {}              // ✗ — режет глаз, нечитабельно

Главный принцип: не должно быть нескольких заглавных букв подряд. Это правило берёт начало из IDE search/navigation — HtmlGenerator доступен по Html или HGen, HTMLGenerator — только по HTML.

Лучше всего — отказаться от аббревиатур: HttpUrlConnection → HttpResource (если контекст ясен), XmlParser → MarkupParser.

Методы

JS-2.6: глаголы.

public String getName() {}              // ✓
public void expand() {}                 // ✓
public boolean isValid() {}             // ✓
public boolean hasOrders() {}           // ✓

public String name() {}                 // ✗ — существительное, выглядит как getter без get
public boolean expanding() {}           // ✗ — gerund, не глагол

Исключение — record accessors: record User(String name) {} — user.name() (без get-префикса) корректно, это часть Java-record-конвенции (Java 16+).

Для не-record классов — getName(), isActive(), hasItems().

Имена тестов

JS-2.6.1: суть кейса.

Два допустимых подхода:

// ✓ — длинное говорящее имя
@Test
public void shouldReturnNullIfResponseEmptyArray() {}

// ✓ — короткое имя + @DisplayName, если длинно
@Test
@DisplayName("should return null if response is empty array")
public void someOtherShorterName() {}

// ✗ — snake_case
public void should_Return_Null_If_Response_Empty_Array() {}

// ✗ — слишком длинное без @DisplayName
public void shouldReturnNullIfResponseEmptyArrayOrExternalSystemIsDownAndStuff() {}

snake_case в Java тест-методах не приветствуется — это convention из других языков. Длинное говорящее имя 50-80 символов — норма; больше — @DisplayName.

Подробнее про структуру test names — см. Test Strategy → один тест (TS-16).

Переменные

JS-2.7: camelCase, lowercase first letter.

int currentValue;                       // ✓
String customerEmail;                   // ✓
List<Order> activeOrders;               // ✓

int PreviousValue;                      // ✗ — выглядит как класс
int Previous_value;                     // ✗ — snake_case
int current_value;                      // ✗ — snake_case

Underscore в Java-именах — только в static final константах (см. ниже) и enum-значениях.

Константы

JS-2.8: UPPER_SNAKE_CASE + static final.

public static final int BUFFER_SIZE = 1024;      // ✓
public static final String DEFAULT_USER = "anon"; // ✓
public static final Duration TIMEOUT = Duration.ofSeconds(30);  // ✓

public final int ARRAY_SIZE = 10;                // ✗ — не static (instance field)
public static final int bufferSize = 1024;       // ✗ — camelCase
public static int BUFFER_SIZE = 1024;            // ✗ — не final (mutable)

UPPER_SNAKE_CASE — сигнал «это константа, известна на этапе компиляции, может использоваться в switch case, не меняется». Если значение static final, но runtime-computed (через init-block или статический initializer) — всё равно UPPER_SNAKE_CASE если immutable.

public static final Pattern EMAIL_PATTERN = Pattern.compile(".+@.+");  // ✓

Что запрещено

Антипаттерн	Правило	Что взамен
package com.example.utils (plural)	JS-2.2	com.example.util
interface IUserService	JS-2.4	interface UserService
class XMLParser	JS-2.5	XmlParser
class IpAddress (2 буквы)	JS-2.5	IPAddress
public boolean expanding()	JS-2.6	isExpanding()
public void test_create_order_success()	JS-2.6.1	createOrder_whenValid_returns201
int PreviousValue	JS-2.7	previousValue
static int BUFFER_SIZE без final	JS-2.8	static final
Method name() для не-record	JS-2.6	getName()

Куда дальше

• Java → раздел 2. Именование — нормативные формулировки.
• Импорты — не wildcard, не оставлять unused.
• Выражения — guard expressions, method references.
• Lombok — @Getter/@Setter вместо ручных accessors.
• Комментарии — хорошее имя устраняет необходимость в комментарии.
• Test Strategy → один тест — детали naming для test methods.
• Checkstyle — TypeName, MethodName, PackageName.