Соглашения по оформлению кода Java (Java Code Conventions)

Данный перевод не претендует на пальму первенства или как наиболее точный перевод! Думаю таких переводов в сети довольного много, может многие из них переведены куда лучше этого =)

Этот перевод я делал для себя в целях ознакомления с данным документом, да и правилам оформления кода в целом. В этом переводе отчасти использовались материалы с этого перевода.

Для себя я старался его сделать максимально удобоваримым для понимания и использования в дальнейшем =) По этому если кто хочет его использовать где-то в других местах, то не забываем указывать ссылку на этот материал или сайт http://www.magnumblog.space;)

А вообще пользуйтесь на здоровье.

1. Введение
   1. Зачем нужны условные обозначения кода
   2. Выражение признательности
2. Имена файлов
   1. Расширения файлов
   2. Общие имена файлов
3. Организация файлов
   1. Файлы с исходным кодом Java
      1. Начальный комментарий
      2. Операторы package и import
      3. Объявления классов и интерфейсов
4. Отступы
   1. Длинна строки
   2. Перенос строки
5. Комментарии
   1. Формат реализации комментариев
      1. Блок комментариев
      2. Однострочный комментарий
      3. Прицепные комментарии
      4. Комментарии в конце строки
   2. Комментарии для документации
6. Объявления
   1. Количество объявлений в строке
   2. Размещение
   3. Инициализация
   4. Объявления классов и интерфейсов
7. Операторы
   1. Простые операторы
   2. Составные операторы
   3. Оператор return
   4. Операторы if, if-else, if-else-if-else
   5. Оператор цикла for
   6. Оператор цикла while
   7. Оператор цикла do-while
   8. Оператор switch
   9. Оператор try-catch
8. Пробелы
   1. Пустые строки
   2. Расстановка пробелов
9. Соглашение об именовании
10. Практическое применение
    1. Обеспечение доступа к экземпляру и переменным класса
    2. Обращение к переменным и методам класса
    3. Константы
    4. Примеры присваивания значение переменным и операторам и т.д.
    5. Различные приёмы программирования
       1. Круглые скобки
       2. Возврат значения
       3. Выражения перед '?' в условном операторе
       4. Специальные комментарии
11. Примеры кода
    1. Пример файла с исходным кодом Java

1 - Введение

1.1 Зачем нужны условные обозначения кода

Соглашения по оформлению кода важны для программистов по ряду причин:

• 80% от стоимости программного обеспечения приходится на его обслуживание.
• Вряд ли какое-либо программное обеспечение все время поддерживается первоначальным разработчиком.
• Соглашения по оформлению кода делают исходный код программ более удобочитаемым, позволяя инженерам более быстро и тщательно понимать новый код.
• Если вы предоставляете исходный код как продукт, вы должны убедится, что он хорошо оформлен и упакован как любой другой продукт который вы создаете

1.2 Выражение признательности

В этом документе содержатся стандарты по оформлению кода на языке Java, представленные в спецификации от Sun Microsystems. Основные вклады от Питера Кинга, Патрика Нотона, Майка ДеМони, Джонни Канервы, Кэти Уолрата и Скотта Хоммеля.

По вопросам, связанным с адаптацией, модификацией или распространением этого документа, пожалуйста, прочитайте наше уведомление об авторских правах по адресу http://java.sun.com/docs/codeconv/html/Copyright.doc.html.

Комментарии к этому документу должны быть отправлены в нашу форму обратной связи по адресу http://java.sun.com/docs/forms/sendusmail.html.

2 - Имена файлов

В этом разделе перечислены наиболее часто используемые имена файлов и их расширения.

2.1 Расширения файлов

В программах написанных на Java используются следующие расширения файлов:

2.2 Общие имена файлов

Часто используемые имена файлов включают:

3 - Организация файлов

Файл состоит из разделов, которые должны быть разделены пустыми строками и необязательным комментарием, идентифицирующим каждую секцию.

Файлы длиной более 2000 строк являются громоздкими и их следует избегать.

Пример форматирования файла с исходным кодом Java приведен в разделе "Пример файла с исходным кодом Java".

3.1 Файлы с исходным кодом Java

Каждый файл с исходным кодом Java содержит один class с ключевым словом public или интерфейс. Когда классы с ключевым словом private и интерфейсы связанны с public классом, то их можно поместить в тот же файл с иходным кодом, что и public класс. Класс с ключевым словом public должен быть размещен как первый класс или интерфейс в файле.

Файлы с исходным кодом Java имеют следующий порядок:

• Начальный комментарий (смотрите "Начальный комментарий")
• Операторы package и import, например:

import java.applet.Applet;
import java.awt.*;
import java.net.*;
		

• Объявления классов и интерфейсов (смотрите "Объявления классов и интерфейсов")

3.1.1 Начальный комментарий

Все файлы с исходным кодом должны начинаться с комментария в стиле языка C, в котором перечислены авторы программы, дата, сведения об авторских правах, а так же кратко описание того, что делает программа. Для примера:

/*
 * Имя класса
 *
 * Информация о версии
 *
 * Информация об авторском праве
 */
	

3.1.2 Операторы Package и Import

Первая строка без комментария в файле с исходным кодом Java это оператор package. После нее следует оператор import. Для примера:

package java.awt;
import java.awt.peer.CanvasPeer;
		

3.1.3 Объявления классов и интерфейсов

В следующей таблице описаны части объявления класса или интерфейса в том порядке, в котором они должны отображаться. Образец с комментариями приведен в "Примере файла с исходным кодом Java"

4 - Отступы

В качестве единицы отступов следует использовать четыре пробела. Точная конструкция отступа (пробелы или символы табуляции) не указана. Табуляция должна быть установлена ровно каждые 8 пробелов (а не 4).

4.1 Длина строки

Избегайте строк длиннее 80 символов, так как они не обрабатываются многими терминалами и инструментами.

Примечание: Примеры для использования в документации должны иметь более короткую длину строки - обычно не более 70 символов.

4.2 Перенос строки

Если выражение не помещается на одной строке, разбейте его в соответствии с этими общими принципами:

• Перенос после запятой.
• Перенос перед оператором.
• Предпочитайте переносы более высокого уровня для переноса нижнего уровня (вложенном уровне).
• Выравнивайте новую строку выражения так, чтобы его начало было на том же уровне как и в предыдущей строке.
• Если приведенные выше правила приводят к запутанному (плохо читающемуся) коду или коду, который сжимается с правым краем, просто введите 8 пробелов вместо этого.

Несколько примеров переноса строки в вызовах методов:

function(longExpression1, longExpression2, longExpression3,
         longExpression4, longExpression5);

var = function1(longExpression1,
                function2(longExpression2,
                          longExpression3));
		

Ниже приведены два примера переноса арифметического выражения. Первое предпочтительнее, так как разрыв происходит вне выражения в скобках, которое находится на более высоком уровне.

longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6;                                // ПРЕДПОЧТИТЕЛЬНЕЙ

longName1 = longName2 * (longName3 + longName4
                         - longName5) + 4 * longname6;      // ИЗБЕГАЙТЕ
		

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

//ОБЫЧНЫЕ ОТСТУПЫ
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
           Object andStillAnother) {
    ...
}

//ОТСТУП НА 8 СИМВОЛОВ, ЧТОБЫ ИЗБЕЖАТЬ ОЧЕНЬ ДЛИННЫХ ОТСТУПОВ
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {
   ...
}
		

Отступы в строках с оператором if следует применить по правилу 8-ми пробелов, так как если использовать стандартные 4-ре пробела, то поиск тела оператора будет затруднителен. Например:

//НЕ ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ
if ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) { //ПЛОХОЙ ПЕРЕНОС
    doSomethingAboutIt();            //СДЕЛАЕТ ЭТУ СРОКУ МЕНЕЕ ЗАМЕТНОЙ (ЛЕГКО ПРОПУСТИТЬ)
}

//ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ В ПОДОБНЫХ СЛУЧАЯХ
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

//ИЛИ ДЕЛАЙТЕ ТАК
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}
		

Вот три приемлемых способа форматирования тернарных выражений:

alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;

alpha = (aLongBooleanExpression)
        ? beta
        : gamma;
		

5 - Комментарии

Программы написанные на языке Java могут иметь два вида комментариев: комментарий реализации и документирующий комментарий. Комментарии реализации - это те, которые применяются в языке C++, обозначаются /*...*/ и //. Документирующие комментарии (известные как "doc comments" или "Javadoc") есть только в Java, и обозначаются /** ... */. Документирующие комментарии могут извлекаться из кода в HTML файл, используя инструмент javadoc.

Комментарии кода используются для описания отдельных строк/блоков кода или целого алгоритма. Комментарии для документирования используются, чтобы описать спецификацию кода (его интерфейс), не зависящую от его реализации. Комментарии для документирования делают для разработчиков, которые будут использовать ваши программы (библиотеки классов) не имея их исходного кода.

Комментарии нужны, чтобы описать код или пояснить моменты, которые сложно понять непосредственно из кода. Комментарии должны содержать лишь ту информацию, которая необходима для чтения и понимания кода программы. Например информацию о том, как откомпилировать связанный пакет или в какой директории он находится не стоит описывать в комментарии.

Обсуждение нетривиальных или неочевидные решений необходимо, но не нужно описывать то, что и так ясно из кода. Такие "избыточные" комментарии очень быстро могут стать неактуальными. В общем, следует избегать любых комментариев, которые могут стать неактуальными по мере развития кода.

Примечание: Частое использование комментариев иногда говорит о низком качество кода. Когда вы чувствуете необходимость добавить комментарий, попробуйте переписать код, чтобы он стал понятнее.

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

/************************
 * Какой то комментарий *
 ************************/
		

Комментарии не должны содержать специальных символов, таких как символ конца страницы или backspace.

5.1 Формат реализации комментариев

В программах могут использоваться 4 вида комментариев: блочные, однострочные, прицепные и комментарии до конца строки.

5.1.1 Блок комментариев

Блочные комментарии используются для описания файлов, методов, структур данных и алгоритмов. Так же их следует использовать в начале каждого файла и перед каждым методом. Они также могут использоваться в других местах, например, внутри методов. Блочные комментарии внутри функции или метода должны иметь отступ на том же уровне, что и код, который они описывают.

Перед блочным комментарием следует оставлять пустую строку, чтобы визуально отделить его от кода. Каждая строка блочного комментария (кроме первой) должна начинаться с символа "*".

/*
 * Это блок комментариев.
 */
		

Если блочный комментарий начинается с "/*-", это означает в данном блоке используется особое форматирование, которое нельзя потерять (Такой блок не будет переформатирован средствами автоформатирования). Например:

/*
 * Этот блочный комментарий содержит очень специфичное
 * форматирование, которое должно игнорироваться средствами автоформатирования
 *
 * один
 *     два
 *         три
 */
		

Примечание: Если вы не используете средства автоформатирования, вам не обязательно использовать "/*-" в коде, но можете сделать это на случай того, что кто-то другой может запустить средства автоформатирования на вашем коде.

Смотрите подробней в "Комментарии для документации"

5.1.2 Однострочный комментарий

Однострочные комментарии (короткие комментарии) можно писать в одной строке используя отступ на уровне соответствующего блока кода, который он описывает. Если комментарий не помещается в одну строку, следует использовать блочный комментарий (смотрите "Блок комментариев"). Однострочному комментарию должна предшествовать пустая строка. Вот пример однострочного комментария в Java-коде (смотрите "Комментарии для документации"):

if (условие) {

    /* Обработка условия. */
    ...
}
		

5.1.3 Прицепные комментарии

Очень короткий комментарий можно расположить на той же строке, что и описываемый код. При этом его следует сдвинуть вправо настолько, чтобы он не сливался с кодом. Если в одном блоке кода присутствует более одного такого комментария, их начало должно быть на одном уровне.

Старайтесь избегать комментирования каждой строчки кода подобным образом.

Пример прицепных комментариев в Java коде (смотрите также "Комментарии для документирования"):

if (a == 2) {
    return TRUE;        /* особый случай */
} else {
    return isprime(a);	/* работает только для нечетных a */
}
		

5.1.4 Комментарии в конце строки

Символами // начинается комментарий, который продолжится до следующей строки (новой строки). Он может занимать всю строку или только ее часть. Его не следует использовать для многострочных комментариев, однако его можно использовать, чтобы закомментировать несколько строк кода. Рассмотрим пример всех трех вариантов его использования:

if (foo > 1) {

    // Сделайте двойной щелчок.
    ...
}
else
    return false;	// Объясните, почему здесь.

//if (bar > 1) {
//
//    // Сделайте тройной щелчок.
//    ...
//}
//else
//    return false;
		

5.2 Комментарии для документирования

Примечание: смотрите "Пример файла с исходным кодом Java" для примеров форматов комментариев, описанных здесь.

Для получения дополнительной информации смотрите "Как написать комментарии к документу для Javadoc", который включает в себя информацию о тегах комментариев документа (@return, @param, @see):

http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

Для получения большей информации о документирующих комментариях и Javadoc, посетите домашнюю страницу Javadoc:

http://java.sun.com/products/jdk/javadoc/

Документирующие комментарии описывают Java классы, интерфейсы, конструкторы, методы и поля. Каждый комментарий помещается в ограничители /**...*/, один комментарий на один элемент API. Такой комментарий должен располагаться непосредственно перед объявлением:

/**
 * Класс Example предоставляет ...
 */
class Example { ...
		

Обратите внимание, что классы и интерфейсы не имеют отступов, в отличии от их членов. Первая строка документирующего комментария (/**) для классов и интерфейсов не имеет отступов; каждая последующая строка документирующего комментария имеет 1 пробел (для вертикального выравнивания звездочек). Члены класса, включая конструкторы, имеют 4 пробела для первой строки документирующего комментария и 5 для остальных.

Если необходимо предоставить информацию о классе, интерфейсе, переменной или методе, не принадлежащую к документации, используйте блочный (смотрите раздел 5.1.1) или однострочный (смотрите раздел 5.1.2) комментарий непосредственно после объявления. Например, детали о реализуемом классе должны идти в таком комментарии в блоке реализации, а не в документирующем комментарии.

Документирующий комментарий не должен располагаться внутри блока реализации метода или конструктора, потому что Java связывает документирующий комментарий с первым после него объявлением.

6 - Объявления

6.1 Количество объявлений в строке

Рекомендуется использовать одно объявление на строку, так как это облегчает комментирование. Другими словами:

int level; // уровень отступа
int size;  // размер таблицы
		

предпочтительней нежели

int level, size;
		

Ни в коем случае нельзя объявлять переменные и функции в одной строке. Например:

long dbaddr, getDbaddr(); // НЕПРАВИЛЬНО!
		

Не помещайте переменные разных типов (имеется в виду не тип самих переменных, а тип данных которые в них хранятся) в одну строку. Например:

int foo, fooarray[]; /* НЕПРАВИЛЬНО! В одной строке нельзя распологать целочисленную переменную и массив данных! */
		

Примечание: В приведенных выше примерах используется один пробел между типом и идентификатором. Другой приемлемой альтернативой является использование табуляции для выравнивания идентификторов в одну линию (использование клавиши Tab которая равна обычно 4-м пробелам), например:

int 	level;          // уровень отступа
int     size;           // размер таблицы
Object	currentEntry;   // текущий выделенный экземпляр таблицы
		

6.2 Размещение

Размещайте объявления только в начале блоков (блоком является любой код, заключенный в фигурные скобки "{"" и "}"). Не ждите объявления переменных до их первого использования; Это может запутать неопытного программиста и затруднить переносимость кода в пределах области.

void MyMethod() {
    int int1;         // Начало блока метода

    if (условие) {
        int int2;     // Начало блока оператора "if"
        ...
    }
}
		

Единственным исключением из этого правила являются индексы циклов for, которые в Java могут быть объявлены в операторе for:

for (int i = 0; i < maxLoops; i++) { ...
		

Избегайте локальных объявлений, перекрывающих объявления более высокого уровня. Например, не объявляйте одну и ту же переменную перед блоком кода и во внутреннем блоке:

int count;
...
func() {
    if (условие) {
        int count;    // ИЗБЕГАЙТЕ!
        ...
    }
    ...
}
		

6.3 Инициализация

Старайтесь инициализировать локальные переменные там, где вы их объявляете. Единственная причина не инициализировать переменную в месте её объявления — если её начальное значение зависит от некоторых предварительных вычислений.

6.4 Объявления классов и интерфейсов

При написании Java классов и интерфейсов необходимо соблюдать следующие правила форматирования:

• Не ставьте пробел между именем метода и скобкой "(" внутри которой указывается список его параметров
• Открывающая скобка "{" ставится в конце той же строки, где указан оператор объявления класса или интерфейса
• Закрывающая скобка "}" ставится на отдельной строке с тем же отступом, что и у соответствующего ему открывающего оператора, кроме случаев, когда имеем пустой оператор, то "}" должна появиться сразу после "{"

class Sample extends Object {
    int ivar1;
    int ivar2;

    Sample(int i, int j) {
        ivar1 = i;
        ivar2 = j;
    }

    int emptyMethod() {}

    ...
}
		

• Между методами должна быть одна пустая строка

7 - Операторы

7.1 Простые операторы

Каждая строка должна содержать не более одного оператора. Например:

argv++; argc--;    // ИЗБЕГАЙТЕ!
		

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

if (err) {
    Format.print(System.out, "error"), exit(1); //ОЧЕНЬ НЕПРАВИЛЬНО!
}
		

7.2 Составные операторы

Составные операторы - это операторы, содержащие списки операторов, заключенные в фигурные скобки "{ операторы }". Примеры приведены в следующих разделах.

• Вложенные операторы должны иметь отступ на один уровень больше, чем составной оператор.
• Открывающая скобка должна быть в конце той строки, с которой начинается составной оператор; закрывающая скобка должна начинаться с новой строки и с отступом, соответствующим началу составного оператора.
• Скобки используются во всех операторах, даже в одиночных, когда они входят в состав управляющей структуры, таких, как оператор if-else или for. Это необходимо, чтобы избежать ошибок в случае добавления новых операторов, когда забыли указать фигурные скобки (если фигурных скобок нет, то управляющая конструкция типа if будет выполнять только одну строку после нее до знака ";").

7.3 Оператор return

Оператор return, возвращающий значение, не должен использовать скобки, если только их использование не сделает возвращаемое значение более понятным. Например:

return;

return myDisk.size();

return (size ? size : defaultSize);
		

7.4 Операторы if, if-else, if-else-if-else

Группа операторов (как и единичное использование) if-else должна иметь следующий вид:

if (условие) {
    операторы;
}

if (условие) {
    операторы;
} else {
    операторы;
}

if (условие) {
    операторы;
} else if (условие) {
    операторы;
} else if (условие) {
    операторы;
}
		

Примечание: операторы if всегда должны использоваться с фигурными скобками "{ }". Избегайте следующей формы:

if (условие) //ИЗБЕГАЙТЕ! ЗДЕСЬ УПУЩЕНЫ ФИГУРНЫЕ СКОБКИ {}!
    оператор;
		

7.5 Оператор цикла for

Оператор цикла for должен иметь следующий вид:

for (инициализация; условие; итерация) {
    операторы;
}
		

Пустой оператор цикла for (тот, в котором вся работа выполняется в инициализации, условии и итерации) должен иметь следующий вид:

for (инициализация; условие; итерация);
		

При использовании оператора запятой в блоке инициализации или итерации оператора цикла for избегайте использования более чем трех переменных. Если необходимо, используйте отдельные операторы перед циклом for (для случая блока инициализации) или в конце цикла (для случая блока итерации).

7.6 Оператор цикла while

Оператор цикла while должен иметь следующий вид:

while (условие) {
    операторы;
}
		

Пустой оператор цикла while должен иметь следующий вид:

while (условие);
		

7.7 Оператор цикла do-while

Оператор цикла do-while должен иметь следующий вид:

do {
    операторы;
} while (условие);
		

7.8 Оператор switch

Оператор switch должен иметь следующую форму:

switch (условие) {
case ABC:
    операторы;
    /* провал */
case DEF:
    операторы;
    break;

case XYZ:
    операторы;
    break;

default:
    операторы;
    break;
}
		

Каждый раз, когда выбор проваливается (не включая оператор break), добавьте комментарий, где обычно находится оператор break. Это показано в предыдущем примере кода с комментарием /* провал */.

Каждый оператор switch должен включать выбор по умолчанию (default). Оператор break в выборе по умолчанию лишний, но он предотвращает возникновение ошибки, если позже еще ​​один выбор добавится.

7.9 Оператор try-catch

Оператор try-catch должны иметь следующий формат:

try {
    операторы;
} catch (ExceptionClass e) {
    операторы;
}
		

8 - Пробелы

8.1 Пустые строки

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

Две пустые строки всегда должны использоваться в следующих случаях:

• Между секциями в файле исходного кода
• Между определениями классов и интерфейсов

Одна пустая строка всегда должна использоваться в следующих случаях:

• Между методами
• Между локальными переменными метода и его первым оператором
• Перед блочным (смотрите раздел 5.1.1) или однострочным (смотрите раздел 5.1.2) комментарием
• Между логическими участками кода внутри метода для улучшения читабельности

8.2 Расстановка пробелов

Разделяющие пробелы должны ставиться при следующих обстоятельствах:

• Ключевое слово, за которым следует скобка, должны быть разделены пробелом. Например:

while (true) {
    ...
}
		

Обратите внимание, что пробел не должен использоваться между именем метода и его открывающей скобкой. Это помогает отличать ключевые слова от вызовов метода.

• Разделяющий пробел должен появляться после запятой в списке аргументов.
• Все бинарные операторы кроме "." должны быть отделены от своих операндов пробелами. Пробелом никогда не должны разделятся операнды и их унарные операторы, такие как унарный минус, инкремент ("++") и декремент ("--") от их операндов. Например:

a += c + d;
a = (a + b) / (c * d);

while (d++ = s++) {
    n++;
}
prints("size is " + foo + "\n");
		

• Выражения в операторе цикла for должны быть разделены пробелами. Например:

for (expr1; expr2; expr3)
		

• За приведением типа должен следовать пробел. Например:

myMethod((byte) aNum, (Object) x);
myFunc((int) (cp + 5), ((int) (i + 3))
                             + 1);
		

9 - Соглашение об именовании

Соглашение об именовании делает программы более понятными, облегчая их чтение. Они также могут дать информацию о функции идентификатора - например, является ли он константой, пакетом или классом, это облегчает понимания и чтение кода.

Правила, приведенные в данном разделе, являются основополагающими. Более конкретные правила приведены в таблице:

class Raster;
class ImageSprite;
					

interface RasterDelegate;
interface Storing;
					

run();
runFast();
getBackground();
					

int   i;
char  *cp;
float myWidth;
					

int MIN_WIDTH = 4;
int MAX_WIDTH = 999;
int GET_THE_CPU = 1;
					

10 - Практическое применение

10.1 Обеспечение доступа к экземпляру и переменным класса

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

Одним из примеров уместного использования public полей может быть случай, когда класс описывает лишь структуру данных, без какого-либо поведения. Другими словами, если бы вы могли использовать struct вместо class (если бы Java поддерживал struct), тогда можно сделать переменные экземпляра класса public.

10.2 Обращение к переменным и методам класса

Избегайте использование объекта для доступа к статическим полям и методам класса. Вместо этого используйте имя класса. Например:

classMethod();          //OK
AClass.classMethod();   //OK

anObject.classMethod();	//ИЗБЕГАЙТЕ!
		

10.3 Константы

Численные константы (литералы) не должны кодироваться напрямую, за исключением -1, 0 и 1, которые могут использоваться в циклах для управления счетчиком.

10.4 Примеры присваивания значение переменным и операторам и т.д.

Избегайте присваивания значения некоторым переменным в одном выражении. Это усложняет чтение. Например:

fooBar.fChar = barFoo.lchar = 'c'; //ИЗБЕГАЙТЕ!
		

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

if (c++ = d++) {	//ИЗБЕГАЙТЕ! В Java запрещено
    ...
}
		

лучше написать так:

if ((c++ = d++) != 0) {
    ...
}
		

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

d = (a = b + c) + r;	//НЕПРАВИЛЬНО!
    

должно быть написано так:

a = b + c;
d = a + r;
    

10.5 Различные приёмы программирования

10.5.1 Круглые скобки

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

if (a == b && c == d)	   // ИЗБЕГАЙТЕ!

if ((a == b) && (c == d))  // ПРАВИЛЬНЕЙ ЗАПИАТЬ ТАК
    

10.5.2 Возврат значения

Попробуйте сделать структуру вашей программы понятной. Например:

if (booleanExpression) {
    return TRUE;
} else {
    return FALSE;
}
    

вместо этого следует записать так:

return booleanExpression;
    

аналогичным образом:

if (условие) {
    return x;
}
return y;
    

лучше записать так:

return (условие ? x : y);
    

10.5.3 Выражения перед '?' в условном операторе

Если выражение содержит бинарный оператор, находящийся перед тернарным оператором ?:, он должен быть заключен в скобки. Например:

(x >= 0) ? x : -x
    

10.5.4 Специальные комментарии

Используйте XXX в комментарии для того, чтобы показать, что этот код неправильный, но работает. Используйте FIXME для того, чтобы показать, что код неправильный и не работает.

11 - Примеры кода

11.1 Пример файла с исходным кодом Java

Следующий пример показывает как форматировать файл с исходным кодом Java, содержащим отдельный класс. Интерфейсы форматируются отдельно. Для более подробного изучения прочтите "Объявление классов и интерфейсов" и "Документирующие комментарии".

/*
 * %W% %E% Имя Фамилия
 *
 * Копирайт (c) 1993-1996 Sun Microsystems, Inc. Все права защищены.
 *
 * Это программное обеспечение является конфиденциальной и закрытой информацией Sun
 * Microsystems, Inc. («Конфиденциальная информация»). Вы не должены
 * раскрывать такую Конфиденциальную информацию и использовать ее только в
 * соответствии с условиями лицензионного соглашения, в которых вы состоите
 * с Sun.
 *
 * SUN НЕ ДАЁТ НИКАКИХ ГАРАНТИЙ, ЯВНЫХ ИЛИ КОСВЕННЫХ (ВКЛЮЧАЯ - НО НЕ
 * ОГРАНИЧИВАЯСЬ ИМИ - ГАРАНТИИ РЕАЛИЗУЕМОСТИ), СООТВЕТСТВИЯ ОПРЕДЕЛЁННОМУ
 * НАЗНАЧЕНИЮ ИЛИ НЕНАРУШЕНИЯ УСЛОВИЙ, ЧТО СОДЕРЖИМОЕ ДАННОЙ СПЕЦИФИКАЦИИ
 * ПОДХОДИТ ДЛЯ КАКИХ-ЛИБО ЦЕЛЕЙ ИЛИ ЧТО ЛЮБОЕ ИСПОЛЬЗОВАНИЕ ИЛИ РЕАЛИЗАЦИЯ
 * ТАКОГО СОДЕРЖИМОГО НЕ БУДЕТ НАРУШАТЬ КАКИХ-ЛИБО ПАТЕНТОВ ТРЕТЬЕЙ СТОРОНЫ,
 * АВТОРСКИХ ПРАВ, КОММЕРЧЕСКОЙ ТАЙНЫ ИЛИ ИНЫХ ПРАВ.
 */
package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Описание класса здесь.
 *
 * @version   1.10 04 Oct 1996
 * @author    Имя Фамилия
 */
public class Blah extends SomeClass {
    /* Здесь может идти комментарий реализации класса. */

    /** Комментарий, документирующий classVar1 */
    public static int classVar1;

    /**
     * Документирующий комментарий к classVar2, который бывает
     * более чем одна строка
     */
    private static Object classVar2;

    /** комментарий, документирующий поле instanceVar1*/
    public Object instanceVar1;

    /** комментарий, документирующий поле instanceVar2 */
    protected int instanceVar2;

    /** комментарий, документирующий поле instanceVar3 */
    private Object[] instanceVar3;

    /**
     * ...комментарий, документирующий метод Blah...
     */
    public Blah() {
        //...здесь идет реализация...
    }

    /**
     * ...комментарий, документирующий метод doSomething...
     */
    public void doSomething() {
        //...здесь идет реализация...
    }

    /**
     * ...комментарий, документирующий метод doSomethingElse...
     * @param someParam описание
     */
    public void doSomethingElse(Object someParam) {
        // ...здесь идет реализация...
    }
}
    

 Версию для оффлайн чтения можно найти в моем репозитории Github