Java-конвенция кода

Материал из AOW

Перейти к: навигация, поиск

Стайлгайд для Java

http://se.math.spbu.ru/SE/Members/ylitvinov/javaStyleguide/

Программы обычно пишутся прежде всего для человека, а уж потом для компьютера. Поэтому на читабельность программы и на то, чтобы она была понятной, надо обращать особое внимание. Неправильная, но понятная программа лучше правильной, но непонятной - в первой легко найти ошибку и поправить, а во вторую сложно вносить изменения. Поэтому существуют стили кодирования - некие соглашения между программистами, если не следовать которым, можно быть непонятым. Например, если написать:

 for (int i = 0; i < 10; ++i);
     System.out.println("Ъ");

все подумают, что Ъ будет напечатан 10 раз, а на самом деле - 1. Есть официальный стайлгайд от Sun. Обязательные к исполнению правила (данный список может меняться, следите за обновлениями):

  • Программа должна собираться без предупреждений компилятора.
  • Вложенные операторы должны выделяться отступом, операторы одного уровня вложенности должны быть на одном уровне отступов. Отступы должны быть 4 пробела или 1 табуляция (но что-то одно во всей программе!). Используйте пустые строки, чтобы выделять логически связные куски кода.
  • В описании класса должны идти открытые конструкторы, затем static и public методы, затем public поля (которых быть на самом деле не должно, см. правило 7), затем private конструкторы и методы, затем private поля
  • На одной строке должно быть только одно определение. Неправильно писать
int a, b;

правильно:

int a; 
int b;
  • Нельзя объявлять переменные, совпадающие по имени с переменными, объявленными в объемлющем блоке (избегайте скрытия переменных).
  • Допустимо, чтобы имена параметров метода и полей совпадали.
  • Не должно быть раскопированного кода. Выделяйте общие куски в отдельные методы.
  • Не должно быть public-полей.
  • Не следует писать несколько операторов на одной строке, например,
if (k < 0) fail = true;

следует писать как

if (k < 0)
  fail = true;
  • Открывающая "{" должна быть на той же строке, что и предшествующий текст, закрывающая "}" - на отдельной строке.
  • Методы разделяются пустой строкой.

Пример:

class Sample extends Object {
    int var1;
    int var2;

    Sample(int i, int j) {
        var1 = i;
        var2 = j;
    }

    int emptyMethod() {}
}
  • По возможности сужайте области видимости переменных, набор допустимых операций и т.д. (например, пишите final везде, где только можно). Тогда если что-то пошло не так, вы сможете узнать об этом уже на этапе компиляции.
  • Не используйте goto. Вообще, старайтесь, чтобы поток выполнения программы был прост и понятен.
  • Одна сущность должна отвечать за одно действие и играть одну роль по всей программе. Один метод должен делать что-то одно, если метод делает что-то и что-то ещё, его надо разбить на два. То же касается классов - у них должна быть чётко очерченная область ответственности. Одну и ту же переменную нельзя использовать в двух различных ролях.
  • Не пишите методов размером больше экрана, разбивайте их на мелкие методы.
  • Выбирайте подходящие имена для переменных, методов и классов. Называйте переменные и методы с маленькой буквы, а свои типы (в т.ч. классы и интерфейсы) с большой. Если в имени переменной или метода содержится несколько слов, то все, кроме первого, должны начинаться с заглавной буквы (без каких-либо символов подчеркивания). Имена переменных (за исключением счетчиков циклов), функций и типов данных не должны быть короче 4 символов.

Например:

class ListNode {
    int value;
    ListNode nextNode;
}
  • Не используйте "магические константы".

Неправильно:

  for (i = 0; i < 10; i++) 

Правильно:


final int dimension = 10; 
 ... 
for (i = 0; i < dimension; i++)

  • Выделяйте пробелами арифметические операции, оператор присваивания и т.д.
  • Не отделяйте пробелами скобки.

Например, не

"System.out.println ("Hello!")" или "System.out.println( "Hello!" )", 

а

"System.out.println("Hello!")"
  • Ставьте пробел после ключевого слова: между if и (, for и ( и т.д. Например, правильно оформленный for:
for (int i = 0; i < maxN; ++i) {         
    System.out.println("Hello, world!\n");     
}
  • Предложения case в операторе switch должны оформляться следующим образом:
case '2':
    ...
    break;
if-else оформляется так:
if (condition) {
    statements;
}

if (condition) {
    statements;
} else {
    statements;
}

if (condition) {
    statements;
} else if (condition) {
    statements;
} else {
    statements;
}
  • Методы-предикаты (возвращающие булево значение) следует именовать следующим образом:

[глагол][предикат]

где "глагол" - глагол бытия (to be) или обладания (to have) в сооветствующей форме, а "предикат" - проверяемое свойство. Например:

boolean isPrime(int n) 

boolean hasColor()

  • При вызове функций-предикатов запрещается сравнивать результат с логическими константами.
if (isPrime(n) == true) - плохой код.
  • Не используйте транслит, пишите все либо по-русски в читабельной в компьютерном классе кодировке, либо по-английски. Например, vstavka() - неудачное название для функции, реализующей алгоритм сортировки вставками.
  • Если вы выделяете системные ресурсы (файловые дескрипторы, etc), то вы обязательно должны их освободить, как только в них отпадает нужда.
  • Каждый вывод данных на экран должен сопровождаться сообщением с пояснением того, что именно выводится. Вообще, пользовательский интерфейс должен быть понятен человеку, ни разу не видевшему программу
  • Каждый ввод пользовательских данных должен сопровождаться приглашением к вводу, объясняющим пользователю, ввод данных какого рода и в каком объеме от него ожидается.
Личные инструменты

Разработка веб-сайтов, автоматизация.
По всем вопросам обращайтесь по телефонам:

+7 495 640 29 90
http://artofweb.ru