Home Original page

codestyle/java/README.md at master · netology-code/codestyle

  1. Файлы и пакеты
  2. Отступы. Длина строки. Переносы строк
  3. Расположение блоков и операторов. Пробелы. Скобки
  4. Имена методов и переменных
  5. Структурирование кода
  6. Комментарии и Javadoc
  7. Импорты
  8. Локальные переменные

1. Файлы и пакеты

  • Имена классов должны быть существительными, первые буквы всех слов — заглавные.
  • Имя файла содержащего публичный класс должно совпадать с именем этого класса (+ расширение .java).
  • В одном файле может находиться только один класс или интерфейс (за исключением вложенных классов и интерфейсов).
  • Имена папок и пакетов состоят только из строчных букв. Слова в многословных названиях разделяются подчеркиванием.
  • Используйте UTF-8, как кодировку для Ваших исходных файлов (она выбирается по умолчанию).
  • Описание файла должно быть в самом начале. Далее идут объявления операторов package и import, причем каждый блок разделяется пустой строкой.

2. Отступы. Длина строки. Переносы строк

  • Отступы должны составлять строго 4 пробельных символа;
class Program {

    public static void main(String[] args) {
        int value1 = 1;
        int value2 = 2;
        int result = value1 + value2;
        System.out.println(result);
    }
}

Перед public static void main(String[] args) 4 пробельных символа Перед int value1 и строками ниже, тоже 4 пробельных символа, относительно предыдущего блока public static void main(String[] args), а вот относительно самого края ихсодного кода уже 8 пробельных символов;

  • Символы табуляции не используются для отступов;
  • Длина строки не должна превышать 100 символов (в редакторе кода серая линия справа обозначает эту границу).
  • При превышении длины строки, выражение разбивается согласно следующим правилам:
    1. перенос после запятой;
    2. перенос перед оператором;
    3. используйте отступ в 8 пробелов для обозначения второй строки разделенного выражения;
    4. последующие строки выравниваются по второй строке либо добавляются новые 8 пробелов для обозначения вложенности.

Пример:

int result = someLongExpression(this, expression, on, first, line)     
        + someLongExpression(this, expression, on, seccond, line)

Многое из описанного выше Android Studio, так же как её родитель Intellij Idea, умеет делать автоматически

  • Windows: Ctrl + Alt + L
  • Linux: Ctrl + Shift + Alt + L
  • macOS: Option + Command + L

3. Расположение блоков и операторов. Пробелы. Скобки

  • Определение переменных нужно располагать в начале блока, а не «ждать» первого использования переменной. Инициализация должна производиться, по возможности, сразу.
void myMethod() {
    int count = 0; // beginning of method block
    if (condition) {
        int int2; // beginning of "if" block
        ...
    }
}
  • Между именем метода и скобками для списка параметров нет пробела.
getStaffList(String name)
  • Параметры разделяются пробелом.
getStaffList(String name, int count)
  • Пробелы окружают любой оператор.
res = getCount();
(a > 10) ? b : c;
  • Ключевое слово и следующая за ним скобка ( должны разделяться пробелом.

  • Открывающаяся скобка { располагается на той же строке, что и сигнатура метода/заголовок if, while-блока и т.п.

  • Закрывающаяся скобка } выровнена по строке начала данного блока.

public Collection getStaffList(String name) {
    Collection contacts = Contact.getList(name, RoleHelper.ROLE_AGENT, null,
    AccessLevel.getStaffDiaryEditLevel(), 0, MAX_NUMBER);
    return ListHelper.getLabelValueList(contacts);
}

  • Методы разделяются пустой строкой, объявления свойств класса располагаются по одному на строку.

  • На строке располагается только один оператор.

if (b) {
    return result;
}

Всё описанное в этом пункте, Android Studio (Intellij Idea) может сделать для вас автоматически с помощью комбинации клавиш:

  • Windows: Ctrl + Alt + L
  • Linux: Ctrl + Shift + Alt + L
  • macOS: Option + Command + L

4. Имена методов и переменных

  • Названия методов должны быть глаголами, первая буква должна быть строчной (например getName(), setYear(int year));
  • Имена переменных должны начинаться со строчной буквы;
  • Придерживайтесь следующих названий полей:
    • Имена полей начинаются с буквы нижнего регистра;
    • Поля public static final (константы) пишутся полностью в верхнем регистре, с использованием подчеркивания (ALL_CAPS_WITH_UNDERSCORES).

5. Структурирование кода

  • Методы должны быть короткими, и выполнять только одну задачу соответствующую его имени;
  • Имена методов должны быть самодокументированными;
  • Шаблоны ООП должны применяться для структурирования и облегчения восприятия.

6. Комментарии и Javadoc

  • Описание файла в самом начале. - комментарий.
  • Для описания классов используется Javadoc, лучше начинать фразу с описательного глагола 3-го лица.
  • Не нужно описывать Javadoc для тривиальных get и set методов.
  • Если метод делает что-то более сложное (например, соблюдение неких ограничений, или если его действия имеют важный эффект вне его самого), тогда его стоит задокументировать. Вообще, любой метод, полезно описывать в Javadoc, неважно public он или нет. Public методы являются частью API, и поэтому необходимы описания в Javadoc
  • Стиль TODO. Используйте комментарии TODO для кода, который является временным, краткосрочным, или хорошим, но не идеальным. Комментарий должен включать в себя «TODO:», например:
// TODO: Remove this code after the UrlTable2 has been checked in.

// TODO: Change this to use a flag instead of a constant.

Если ваш комментарий имеет вид «В будущем сделать что-то», то убедитесь, что он включает в себя конкретную дату (1 января 2011 года), или конкретное событие «Удалить после выхода версии 2.1».

7. Импорты

Порядок операторов импорта следующий:

  1. Android импорты.

  2. Сторонние импорты ( com, junit, net, org).

  3. java и javax.

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

  • Отсортированы по алфавиту внутри каждой группы.
  • Заглавные буквы должны быть впереди букв нижнего регистра (например, Z перед a).
  • Главные группы должны разделяться пустой строкой.

Как хорошо что вам не придется делать этого самостоятельно, Android Studio (Intellij Idea) упорядочит их автоматически по сочетанию клавиш.

  • Windows: Ctrl + Alt + L
  • Linux: Ctrl + Shift + Alt + L
  • macOS: Option + Command + L

8. Локальные переменные

  • Область видимости локальных переменных должна сводиться к минимуму. Делая это, вы улучшаете читаемость и поддерживаемость кода, а также уменьшаете вероятность ошибок.

  • Каждая переменная должна объявляться в самом глубоком блоке, который окружает все возможные места использования переменной.

  • Локальные переменные должны объявляться в том месте, где впервые необходимо её использовать.

  • Почти каждая локальная переменная нуждается в инициализаторе.

  • Отложите объявление локальной переменной, пока вы не узнаете, как ее инициализировать.

! Исключение:

Это исключение касается блока try-catch. Если переменная инициализируется при помощи оператора return метода, который выбрасывает проверяемое исключение, то она должна инициализироваться в блоке try. Если же переменная должна использоваться вне блока try, тогда она объявляется перед ним, неважно, знаете ли вы, как её нужно инициализировать, или нет:

// Instantiate class cl, which represents some sort of Set 
Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set 
s.addAll(Arrays.asList(args));

Однако этот случай можно обойти при помощи инкапсуляции блока try-catch в методе.

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set 
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set 
Set s = createSet(cl);
s.addAll(Arrays.asList(args));
  • Переменные в циклах должны объявляться внутри самого оператора, если только нет непреодолимой причины этого не делать.
for (int i = 0; i <= n; i++) {
    doSomething(i);
}

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}