Стайлгайд для Java
Программы обычно пишутся прежде всего для человека, а уж потом для компьютера. Поэтому на читабельность программы и на то, чтобы она была понятной, надо обращать особое внимание. Неправильная, но понятная программа лучше правильной, но непонятной - в первой легко найти ошибку и поправить, а во вторую сложно вносить изменения. Поэтому существуют стили кодирования - некие соглашения между программистами, если не следовать которым, можно быть непонятым. Например, если написать:
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), то вы обязательно должны их освободить, как только в них отпадает нужда.
- Каждый вывод данных на экран должен сопровождаться сообщением с пояснением того, что именно выводится. Вообще, пользовательский интерфейс должен быть понятен человеку, ни разу не видевшему программу
- Каждый ввод пользовательских данных должен сопровождаться приглашением к вводу, объясняющим пользователю, ввод данных какого рода и в каком объеме от него ожидается.