Изменение в регламенте Code Style для Java

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

1 Введение

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

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

2.1 Расширения файлов
2.2 Общие имена файлов

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

3.1 Файлы с исходным кодом Java
3.1.1 Начальный комментарий
3.1.2 Операторы package и import
3.1.3 Объявления классов и интерфейсов

4 Отступы

4.1	Длинна строки
4.2	Перенос строки

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

5.1	Формат реализации комментариев
5.1.1 Блок комментариев
5.1.2 Однострочный комментарий
5.1.3 Прицепные комментарии
5.1.4 Комментарии в конце строки
5.2 Комментарии для документации

6 Объявления

6.1	Количество объявлений в строке
6.2	Размещение
6.3	Инициализация
6.4	Объявления классов и интерфейсов

7 Операторы

7.1 Простые операторы
7.2 Составные операторы
7.3 Оператор return
7.4 Операторы if, if-else, if-else-if-else
7.5 Оператор цикла for
7.6 Оператор цикла while
7.7 Оператор цикла do-while
7.8 Оператор switch
7.9 Оператор try-catch

8 Пробелы

8.1	Пустые строки
8.2	Расстановка пробелов

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

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

10.1 Обеспечение доступа к экземпляру и переменным класса
10.2 Обращение к переменным и методам класса
10.3 Константы
10.4 Примеры присваивания значение переменным и операторам и т.д.
10.5 Различные приёмы программирования
10.5.1 Круглые скобки
10.5.2 Возврат значения
10.5.3 Выражения перед '?' в условном операторе
10.5.4 Специальные комментарии

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

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



1 - Введение

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

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

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




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

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


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

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

--------------------------------
Тип файла	       | Расширение
--------------------------------
Для исходного кода | .java
--------------------------------
Для байт-кода	   | .class
--------------------------------


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

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

Имя файла	Применение

GNUmakefile	Зарезервированное имя для создаваемых файлов. Мы используем gnumake для создания нашего программного обеспечения.
README	    Зарезервированное имя файла в котором содержится информация о файлах находящихся в той же директории.



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"

-------------------------------------------------------------------------------------
Часть объявления класса/интерфейса|                  Заметки
-------------------------------------------------------------------------------------
Комментарий для документации по   | Смотрите в "Комментарии для документации" какая
классам и интерфейсам (/**...*/)  | информация должна содержатся в этом комментарии
-------------------------------------------------------------------------------------
Оператор class или interface      |
-------------------------------------------------------------------------------------
Если необходимо, то указать       | Здесь содержится любая дополнительная информация
комментарий реализации            | по классу или интерфейсу, которая не подходит для
класса/интерфейса (/*...*/)       | документирующего комментария.
-------------------------------------------------------------------------------------
(static) Переменные класса        | Сначала переменные класса public, затем protected,
                                  | и только потом private
-------------------------------------------------------------------------------------
Переменные экземпляра             | Сперва public, затем protected, и только потом
                                  | private.
-------------------------------------------------------------------------------------
Конструкторы                      |
-------------------------------------------------------------------------------------
Методы                            | Методы должны быть сгруппированными по
                                  | функциональности, а не по области или доступности.
                                  | Для примера метод класса private может находится
                                  | между двумя public методами экземпляра. Цель в
                                  | облегчении чтения и понимания кода.
--------------------------------------------------------------------------------------




4 -	Отступы

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


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

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

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


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

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

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

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

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 следует применить по правилу 2 таба, так как если использовать стандартный таб, то поиск тела оператора будет затруднителен. Например:

//НЕ ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ
if ((условие1 && условие2)
    || (условие3 && условие4)
    ||!(условие5 && условие6)) { //ПЛОХОЙ ПЕРЕНОС
    doSomethingAboutIt();            //СДЕЛАЕТ ЭТУ СРОКУ МЕНЕЕ ЗАМЕТНОЙ (ЛЕГКО ПРОПУСТИТЬ)
}

//ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ В ПОДОБНЫХ СЛУЧАЯХ
if ((условие1 && условие2)
        || (условие3 && условие4)
        ||!(условие5 && условие6)) {
    doSomethingAboutIt();
}

//ИЛИ ДЕЛАЙТЕ ТАК
if ((условие1 && условие2) || (условие3 && условие4)
        ||!(условие5 && условие6)) {
    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[]; /* НЕПРАВИЛЬНО! В одной строке нельзя располагать целочисленную переменную и массив данных! */

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

int 	level;			// уровень отступа
int1	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;
                   | с большой буквы с большой буквы).                 |
                   | Постарайтесь, чтобы ваши имена классов были       |
                   | простыми и наглядными. Используйте                |
                   | целые слова - избегайте сокращений и аббревиатур  |
                   | (если только аббревиатура делает имя класса более |
                   | наглядным и понятным, чем длинная форма, например |
                   | такие как URL или HTML).                          |
----------------------------------------------------------------------------------------------------
Интерфейсы         | Имена интерфейсов должны так же как имена классов | interface RasterDelegate;
                   | начинаться с заглавных букв и именоваться         | interface Storing;
                   | согласно тех же правил.                           |
----------------------------------------------------------------------------------------------------
Методы             | Методы должны быть глаголами, набранными в        | run();
                   | смешанном регистре, первая буква первого слова в  | runFast();
                   | нижнем регистре, у всех последующих слов первая   | getBackground();
                   | буква в верхнем регистре.                         |
-----------------------------------------------------------------------------------------------------
Переменные         | За исключением переменных, все экземпляры классов | int   i;
                   | и констант классов набираются в смешанном         | char  *cp;
                   | регистре с первым символом в нижнем регистре.     | float myWidth;
                   | Последующие слова набираются с большой буквы.     |
                   | Имена переменных должны быть короткими,           |
                   | но имеющими смысл. Выбранное имя переменной       |
                   | должно быть запоминающееся - то есть кратко       |
                   | описывающим то, что в ней содержится.             |
                   | Односимвольных имен переменных следует избегать,  |
                   | за исключением временных "одноразовых" переменных.|
                   | Общепринятыми именами для временных переменных    |
                   | являются i, j, k, m и n для целых чисел; c, d и e |
                   | для символов                                      |
------------------------------------------------------------------------------------------------------
Константы          | Имена переменных объявленные константами класса,  | int MIN_WIDTH = 4;
                   | и ANSI константы должны быть набраны в верхнем    | int MAX_WIDTH = 999;
                   | регистре (заглавными буквами) с разделяемые       | int GET_THE_CPU = 1;
                   | знаком подчеркивания "_" между словами.           |
                   | (ANSI констант следует избегать для более         |
                   | легкой отладки.)                                  |
------------------------------------------------------------------------------------------------------




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) {
        // ...здесь идет реализация...
    }
}