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

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

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

JVM выполняет int X=1;if(X>0){return"a";} ровно с той же скоростью, что и хорошо отформатированный код. Соглашения существуют для людей: код читают гораздо чаще, чем пишут, и единообразный стиль снимает слой трения при каждом чтении. Второй, практический выигрыш — это гигиена diff: когда все форматируют одинаково, 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 и их именование в верхнем-snake-case с первого взгляда сигнализирует каждому читателю «это никогда не меняется» — соглашение кодирует намерение, которое компилятор выразить не может.
grossPrice(100.00) = 120.00 пришло из метода, чьё глагольное имя в camelCase читается как инструкция. Параметр netPrice и использование TAX_RATE в теле делают расчёт самодокументируемым; вы понимаете его без комментария.
grades = [A, B, C] создаётся методом classify, написанным в стиле скобок K&R с явными скобками в каждой ветви — даже в однострочных ветвях с return. Эти скобки не дают позднейшей правке случайно создать «висячую инструкцию».
total name length = 10 исходит из расширенного цикла for по List<String>, объявленной с типом интерфейса слева, а не ArrayList. Программирование на интерфейс — это соглашение, оставляющее остальной части кода свободу менять реализации.
totalLength is even показывает булево значение, названное как вопрос (isEven), питающее короткий, одноцелевой тернарный оператор. Соглашения вроде этих невидимы, когда им следуют, и режут глаз, когда их нарушают — именно поэтому команды их автоматизируют.

Что охватывает остальная часть этой части

Практики чистого кода, эффективное именование, неизменяемость, шаблоны обработки ошибок и принципы проектирования (SOLID, DRY), которые строятся на этом фундаменте. Соглашения — это поверхностный слой; следующие главы переходят от того, как код выглядит, к тому, как он структурирован.

Practice

Практика

Your team is reviewing a pull request and someone declares a configuration value as 'private static final int maxRetries = 3;'. Following standard Java coding conventions, what is the issue?

A 'static final' constant should be named in UPPER_SNAKE_CASE, so it should be 'MAX_RETRIES'
Constants are not allowed to be 'private' in Java, so the access modifier must be removed
The field must use 'PascalCase' because it is declared at class level
Integer constants must be declared without 'final' so the JVM can optimize them