Соглашения по написанию кода на Java и руководства по стилю

Соглашения по написанию кода — это общие правила, благодаря которым код на Java выглядит так, будто его написал один человек, даже когда над ним работает команда из пятидесяти разработчиков. Они охватывают именование, отступы, расстановку скобок, длину строк и структуру файлов — ни одна из этих вещей не волнует компилятор, но именно они определяют, сможет ли следующий читатель (часто вы сами, спустя несколько месяцев) быстро разобраться в методе или будет вынужден его расшифровывать. В Java очень сильные соглашения, потому что они были опубликованы рано — в оригинальном документе Sun Code Conventions for the Java Programming Language — и с тех пор остаются удивительно стабильными.

Почему соглашения важнее компилятора

JVM выполняет int X=1;if(X>0){return"a";} ровно с той же скоростью, что и хорошо отформатированный код. Соглашения существуют для людей: код читают гораздо чаще, чем пишут, а единый стиль устраняет один из слоёв трений при каждом прочтении. Второй практический выигрыш — чистота диффов: когда все форматируют одинаково, diff в системе контроля версий показывает реальные изменения логики, а не шум от переформатирования. Большинство команд применяют единый стиль автоматически (с помощью форматтера) именно для того, чтобы стиль перестал быть темой для обсуждения на код-ревью.

Именование: соглашения, которые используются в каждой строке

Имена несут почти весь смысл программы, и правила именования в Java почти универсальны по всей экосистеме:

Элемент	Соглашение	Пример
Класс / интерфейс / перечисление	`PascalCase`, существительное	`OrderService`, `HttpClient`
Метод	`camelCase`, глагольная фраза	`parseDate`, `isEmpty`
Поле / локальная переменная	`camelCase`, существительное	`retryCount`, `userName`
Константа (`static final`)	`UPPER_SNAKE_CASE`	`MAX_RETRIES`, `DEFAULT_PORT`
Параметр типа	одна заглавная буква	`T`, `K`, `V`, `E`
Пакет	только строчные буквы, через точку	`com.example.billing`

public class InvoiceCalculator {        // PascalCase class
  private static final int MAX_ITEMS = 100;  // UPPER_SNAKE_CASE constant
  private int lineCount;                 // camelCase field

  public boolean isOverLimit() {         // camelCase verb, boolean reads as a question
    return lineCount > MAX_ITEMS;
  }
}

Избегайте аббревиатур, не являющихся отраслевым стандартом (accelerationTime, а не accTime), и пусть длина имени соответствует его области видимости — индекс цикла может быть i, но поле, живущее на протяжении всего времени существования объекта, заслуживает полного слова.

Форматирование: скобки, отступы и длина строк

В Java повсеместно используется стиль расстановки скобок K&R: открывающая скобка стоит на той же строке, что и объявление, а закрывающая выравнивается под началом оператора. Стандартный отступ — 4 пробела (в официальных руководствах никогда не табуляция), а строки ограничены разумной шириной: классическое ограничение — 80 символов; современные руководства, например Google, используют 100.

// K&R: opening brace on the same line, always use braces
if (user.isActive()) {
  sendWelcome(user);
} else {
  queueReminder(user);
}

// Even a one-line body gets braces — it prevents the classic "dangling statement" bug
for (Order order : orders) {
  total += order.amount();
}

Несколько правил, которые предотвращают самые распространённые замечания на код-ревью: один оператор на строку, одна пустая строка между методами, пробел после ключевых слов (if (, а не if(), и никакого пробела в конце строки.

Признанные руководства по стилю

Соглашения редко изобретают с нуля — обычно выбирают опубликованное руководство и поручают его соблюдение инструменту:

Руководство	Отступ	Ширина строки	Примечания
Oracle/Sun Code Conventions	4 пробела	80	Оригинальное; фундаментальное, но устаревшее
Google Java Style Guide	2 пробела	100	Широко применяется; поддерживается инструментом `google-java-format`
Android (AOSP)	4 пробела	100	Основано на Google, адаптировано для Android

Конкретное руководство важно меньше, чем выбор одного и его последовательное применение. Такие инструменты, как Checkstyle (проверяет стиль и ломает сборку при нарушениях), Spotless и google-java-format (автоформатирование при сохранении или коммите), а также форматтеры IDE полностью устраняют человеческий фактор.

Рабочий пример: правила соглашений в действующем коде

Компилятор слеп к стилю, поэтому запускаемая программа не может «тестировать» форматирование напрямую. Зато она может задействовать правила именования и структуры в реальном коде — константы, методы в camelCase, скобки в стиле K&R, переменные с типом-интерфейсом — и вывести результаты, подтверждающие, что каждый элемент выполняет свою роль.

java— editable, runs on the server

import java.util.List;
import java.util.ArrayList;

public class CodingConventionsDemo {

// Constants are UPPER_SNAKE_CASE. Classes are PascalCase, methods/fields are camelCase.
  private static final int MAX_RETRIES = 3;
  private static final double TAX_RATE = 0.20;

// A method name is a verb phrase; it reads like an instruction.
  private static double grossPrice(double netPrice) {
    return netPrice * (1 + TAX_RATE);
  }

// Braces use K&R style: opening brace on the same line, always braces even for one statement.
  private static String classify(int score) {
    if (score >= 90) {
      return "A";
    } else if (score >= 75) {
      return "B";
    } else {
      return "C";
    }
  }

public static void main(String[] args) {
    // Local variables: descriptive camelCase names, declared close to first use.
    double net = 100.0;
    System.out.printf("MAX_RETRIES constant = %d%n", MAX_RETRIES);
    System.out.printf("grossPrice(%.2f) = %.2f%n", net, grossPrice(net));

// One statement per line; consistent 4-space (here 2 in source) indentation.
    int[] scores = {95, 80, 60};
    List<String> grades = new ArrayList<>();
    for (int s : scores) {
      grades.add(classify(s));
    }
    System.out.println("grades = " + grades);

// Prefer the enhanced for-loop and interface types on the left (List, not ArrayList).
    List<String> names = List.of("ann", "bob", "cleo");
    int totalLength = 0;
    for (String name : names) {
      totalLength += name.length();
    }
    System.out.println("total name length = " + totalLength);

// Booleans read as questions; ternaries stay short and single-purpose.
    boolean isEven = totalLength % 2 == 0;
    System.out.println("totalLength is " + (isEven ? "even" : "odd"));
  }
}

Что следует вынести из запуска:

MAX_RETRIES constant = 3 показывает константу UPPER_SNAKE_CASE в использовании. Объявление значений как private static final и именование их в верхнем регистре со знаком подчёркивания сигнализирует каждому читателю с первого взгляда: «это никогда не изменится» — соглашение кодирует намерение, которое компилятор не может передать.
grossPrice(100.00) = 120.00 получено от метода, чьё имя в camelCase читается как инструкция. Параметр netPrice и использование TAX_RATE в теле делают вычисление самодокументирующимся; вы понимаете его без комментария.
grades = [A, B, C] формируется методом classify, написанным в стиле скобок K&R с явными скобками на каждой ветке — даже на однострочных. Именно эти скобки не дают последующему редактированию случайно создать «повисший оператор».
total name length = 10 получено из расширенного цикла for по List<String>, объявленному с типом интерфейса слева, а не ArrayList. Программирование на интерфейс — соглашение, которое позволяет остальному коду свободно менять реализации.
totalLength is even показывает boolean, названный как вопрос (isEven), питающий короткий однозначный тернарный оператор. Подобные соглашения незаметны, когда соблюдаются, и режут глаз, когда нарушаются — именно поэтому команды автоматизируют их.

Что охватывает остальная часть этого раздела

Соглашения — это поверхностный слой; следующие главы движутся от того, как код выглядит, к тому, как он структурирован:

Чистый код — практики, позволяющие сохранять методы небольшими и читаемыми, выходя за рамки форматирования.
Лучшие практики именования — выбор имён, которые говорят сами за себя.
Лучшие практики неизменяемости — проектирование объектов, которые нельзя изменить после создания.
Принципы SOLID — правила проектирования, определяющие зависимости между классами.

Практика

Ваша команда проверяет pull request, и кто-то объявляет значение конфигурации как 'private static final int maxRetries = 3;'. Следуя стандартным соглашениям Java, в чём проблема?

Константа 'static final' должна быть названа в UPPER_SNAKE_CASE, то есть должна называться 'MAX_RETRIES'Константы не могут быть 'private' в Java, поэтому модификатор доступа необходимо убратьПоле должно использовать 'PascalCase', поскольку оно объявлено на уровне классаЦелочисленные константы должны объявляться без 'final', чтобы JVM могла их оптимизировать