Skip to content

Latest commit

 

History

History
 
 

java

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Правила оформления кода на Java

  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;
  • Ключевое слово и следующая за ним скобка ( должны разделяться пробелом.
while (b < 100) {
    …
}

  • Открывающаяся скобка { располагается на той же строке, что и сигнатура метода/заголовок 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());
}