Java Style Guide

Свод правил для Java-кода: именование, импорты, выражения, отступы. Цель — единый, читаемый и поддерживаемый код, а не формальная проверка.

Базовый принцип (JS-1.1): любое нарушение руководства допустимо, если оно улучшает читаемость. Это не индульгенция «писать как хочется» — от автора ожидается явное объяснение, чем нарушение лучше.

Каждое правило имеет код (JS-2.5, JS-4.7, …) — на эти коды ссылается скилл java-style-review в findings.

---

1. Общие рекомендации

JS-1.1 Любое нарушение допустимо, если оно улучшает читаемость

Это не индульгенция «писать как хочется». От автора ожидается явное объяснение, чем именно нарушение лучше — в коде или в описании PR. Цель руководства — улучшить читаемость, понимание и общее качество кода, а не превратить ревью в формальную проверку.

---

2. Именование

JS-2.1 Имена пакетов — lowercase, без спецсимволов

Без подчёркиваний, дефисов, цифр в начале.

package com.example.orderservice;       // PREFER
package com.example.order_service;      // AVOID

JS-2.2 Без множественного числа в пакетах

Следуем java.util (не java.utils).

package com.example.util;               // PREFER
package com.example.utils;              // AVOID

JS-2.3 Имена классов — существительные

class Car {}                            // PREFER
class Running {}                        // AVOID

JS-2.4 Имена интерфейсов — существительные или прилагательные на -able

Не начинаем с I — это привычка из C# / .NET.

interface Runnable {}                   // PREFER
interface Comparable {}                 // PREFER
interface IEnumerable {}                // AVOID

JS-2.5 Аббревиатуры

Не должно быть нескольких заглавных подряд. Лучше — отказаться от аббревиатур.

• 2 буквы — обе CAPS.
• 3+ букв — только первая буква CAPS (цифры не считаются).

class IOStream {}                       // PREFER (2 буквы)
class IoStream {}                       // AVOID

class XmlParser {}                      // PREFER (3 буквы)
class XMLParser {}                      // AVOID

class Pk2dfCertificate {}               // PREFER
class C2CTariff {}                      // PREFER (C2C — 2 «буквы», цифра не считается)
class C2сTariff {}                      // AVOID

JS-2.6 Имена методов — глаголы или описание действия

public String getName() {}              // PREFER
public String name() {}                 // AVOID

public void expand() {}                 // PREFER
public boolean expanding() {}           // AVOID

JS-2.6.1 Имена тестов

Имя теста должно отражать суть тест-кейса. Два допустимых подхода:

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

// PREFER — короткое имя + @DisplayName
@Test
@DisplayName("should return null if response is empty array")
public void someShorterName() {}

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

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

JS-2.7 Имена переменных — camelCase, начинаются с lowercase

int currentValue;                       // PREFER
int PreviousValue;                      // AVOID

JS-2.8 Имена констант — UPPER_SNAKE_CASE + static final

public static final int BUFFER_SIZE = 1024;   // PREFER
public final int ARRAY_SIZE = 10;             // AVOID — не static

---

3. Импорты

JS-3.1 Без wildcard-импортов

import some.java.package.ParticularClass;     // PREFER
import some.java.package.*;                   // AVOID

Исключение — java.util.*.

JS-3.2 Без неиспользуемых импортов

---

4. Выражения

JS-4.1 Сложность булева выражения ≤ 3

Считаются операторы && и ||. Больше — код трудно читать, отлаживать, поддерживать.

boolean good = (!a && b) | (a || !b) ^ a;     // PREFER (3)
boolean bad  = (a && b) && c && (c || b);     // AVOID (4)

JS-4.2 Без C-стиля объявления массивов

int[] nums;                             // PREFER
String strs[];                          // AVOID

JS-4.3 Порядок модификаторов

public → protected → private → static → final → transient → volatile → synchronized

JS-4.4 Без неявных модификаторов

• В интерфейсе методы не помечают public / abstract (они и так такие).
• Вложенные enum и interface не помечают static.

JS-4.5 Method reference вместо лямбды, где это имеет смысл

filter(someStrings::contains);          // PREFER
filter(s -> someStrings.contains(s));   // AVOID

JS-4.6 Большие лямбды — в named methods

Если в лямбде логика «больше одного выражения», вынеси её в отдельный метод и передавай method reference.

JS-4.7 Guard expression вместо вложенных условий

public void someMethod() {              // PREFER
    if (!condition) {
        throw e;
    }
    doSomething();
}

public void someMethod() {              // AVOID
    if (condition) {
        doSomething();
    } else {
        throw e;
    }
}

---

5. Отступы и форматирование

JS-5.1 Длина строки ≤ 120 символов

Включая отступы.

JS-5.2 Перенос длинных выражений

• После запятой (для аргументов / списков):

  List<String> colors = Arrays.asList("red", "green", "blue");
  

• Перед оператором:

  int sum = a
      + b;
  

• Сопоставление с началом выражения:

  long total = firstValue
               + secondValue
               + thirdValue;
  

  String message = String.format(
      "User: %s, Age: %d, Score: %f",
      userName, userAge, userScore
  );
  

JS-5.3 Без горизонтального выравнивания переменных

public class Entity {
    public String name;                 // PREFER
    public int age;
}

public class Entity {
    public String name;                 // AVOID — выравнивание ломается в diff
    public int    age;
}

---

Настройка IDE (IntelliJ IDEA)

1. Берём checkstyle.xml из проекта.
2. Ставим плагин CheckStyle-IDEA.
3. File → Settings → Code Style → Java → Import Scheme → Checkstyle Configuration.
4. В корне проекта кладём .editorconfig для отступов.
5. Запускаем сканирование проекта в плагине.

---

Дальше

• Скилл java-style-review в usecase-pattern-skills — автоматическое ревью по этим правилам, с цитированием кодов в findings.
• REST API Style Guide — правила контракта API в том же духе.
• Use Case Pattern — методология поверх стиля кода.