Готовый перевод Java Code Conventions / Соглашения по оформлению кода Java: Java Code Conventions

Внимание! Этот перевод, возможно, ещё не готов, так как модераторы установили для него статус «идёт перевод»

***

Соглашения по оформлению Java-кода

12 сентября 1997

***

Информация об авторских правах

2550 Гарсия-авеню, Маунтин-Вью, Калифорния 94043-1100 США

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

Информация, описанная в этом документе может быть защищена одним или несколькими патентами США, иностранными патентами, или приложениями, находящимися на стадии разработки.

ТОРГОВЫЕ МАРКИ

Sun, Sun Microsystems, Sun Microelectronics, логотип Sun, SunXTL, JavaSoft, JavaOS, логотип JavaSoft, Java, HotJava Views, HotJJavaChips, picoJava, microJava, UltraJava, JDBC, логотип Java Cup и Steam, "Write Once, Run Anywhere" и Solaris являются торговыми марками или зарегистрированными торговыми марками Sun Microsystems, Inc. в Соединенных Штатах и других странах.

UNIX ® является зарегистрированным товарным знаком в США и других странах, лицензируемой исключительно через X/Open Company, Ltd.

Adobe ® является зарегистрированной торговой маркой компании Adobe Systems, Inc.

Netscape Navigator™ является торговой маркой компании Netscape Communications Corporation.

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

ЭТОТ ДОКУМЕНТ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ» БЕЗ ГАРАНТИЙ ЛЮБОГО РОДА, ЯВНЫХ ИЛИ НЕЯВНЫХ, В ТОМ ЧИСЛЕ, ПРЕДПОЛАГАЕМЫХ ГАРАНТИЙ ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ, ИЛИ НЕНАРУШЕНИЯ ПРАВИЛ.

ЭТОТ ДОКУМЕНТ МОЖЕТ СОДЕРЖАТЬ ТЕХНИЧЕСКИЕ НЕТОЧНОСТИ ИЛИ ТИПОГРАФСКИЕ ОШИБКИ. ПРИВЕДЕННАЯ ЗДЕСЬ ИНФОРМАЦИЯ ПЕРИОДИЧЕСКИ ОБНОВЛЯЕТСЯ; ЭТИ ИЗМЕНЕНИЯ БУДУТ ВНЕСЕНЫ В СЛЕДУЮЩИЕ РЕДАКЦИИ ДОКУМЕНТА. SUN MICROSYSTEMS, INC. МОЖЕТ ДЕЛАТЬ ИСПРАВЛЕНИЯ И/ИЛИ ИЗМЕНЕНИЯ В ПРОДУКТЕ(АХ) И/ИЛИ ПРОГРАММЕ(АХ), ОПИСАННЫХ В ЭТОМ ДОКУМЕНТЕ, В ЛЮБОЕ ВРЕМЯ.

Доступно для вторичной переработки

***

1 Введение

1.1. Зачем нужны соглашения по оформлению кода

1.2 Благодарности

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

2.1 Суффиксы файлов

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

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

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

3.1.1 Заголовочные комментарии

3.1.2 Пакеты и импорты

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..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% расхода времени при использовании компонента программного обеспечения уходит на его обслуживание.

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

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

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

1.2. Благодарности

Этот документ отражает стандарты написания кода на языке Java представленные в Java Language Speciﬁcation, от Sun Microsystems, Inc. Спасибо Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath, и Scott Hommel.

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

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

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

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

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

JavaSoft использует следующие расширения файлов:

Тип файла |Расширение

-----------------------

Исходный Java-код |.java

Java-байткод |.class

2.2. Общепринятые имена файлов

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

Имя файла | Использование

-----------------------

GNUmakefile | Предпочтительное имя для make-файлов. Мы используем gnumake для сборки нашего программного обеспечения.

README | Предпочтительное имя файла, который суммирует содержимое определенного каталога.

3. Структура файла

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

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

В качестве примера правильного оформления Java программы, см. "Java Source File Example" на стр. 19.

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

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

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

* Открывающие комментарии (см. "Открывающие комментарии" на стр. 4)

* Сведения о пакете и импорте; например:

import java.applet.Applet;

import java.awt.*;

import java.net.*;

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

3.1.1. Открывающие комментарии

Все файлы исходники должны начинаться с комментария в стиле С, который дает список программиста(ов), дату, авторские права, а также краткое описание назначения программы. Например:

* Имя класа

Информация о версии

* Примечание к копирайту

3.1.2. Сведения о пакете и импорте

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

package java.awt;

import java.awt.peer.CanvasPeer;

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

Приведенная ниже таблица описывает объявление части класса или интерфейса в порядке их появления. См. "Пример файла исходника Java" на стр. 19 для примера с комментариями.

|объявление части класса / интерфейса | примечания

-----------------------------------------------------------------------------------

1 | Комментарии к документации класса/интерфейса (/**...*/) | Смотрите “Комментарии к документации” на стр. 9 с информацией о том, что должно быть в этом комментарии.

2 | Операторы class или interface

3 | Комментарии о реализации класса/интерфейса (/*...*/), если необходимо | Эти комментарии должны содержать расширенную информацию о классе/интерфейсе, которая не относится к комментариям документации класса/интерфейса

4 | Статические переменные класса | Сначала public переменные класса, затем protected, затем пакетные (без спецификатора доступа) и затем private.

5 | Не статические переменные | Сначала public, затем protected, затем пакетные (без спецификатора доступа) и затем private.

6 | Конструкторы

7 | Методы | Эти методы должны группироваться больше по функциональности чем по области видимости или доступности. Например, private метод класса может быть между двумя случайными public методами. Цель – сделать чтение и понимание кода проще.

Отступы

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

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

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

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

Переносы строк

В случах, кода выражение не входит на одну строку, сделайте переход на другую в соотвествии с этими общими принципами:

* начинайте новую строку после запятой

* начинайте новую строку после оператора

* переходите на новую строку на более высоком уровне в коде

* когда часть выражения переносится на новую строку, начинайте ее на том же уровне, на котором находится начало выражения

* если правила, указанные выше, приводят к тому, что код плохо читается или слишком сдвинут вправо, то просто делайте отступ в 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”) встречаются только в Java и ограничиваются / **...*/. На основе документирующих комментариев с помощью утилиты javadoc могут быть созданы файлы документации в формате HTML.

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

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

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

Замечание: Частота комментариев иногда отражает низкое качество кода. Если Вы почувствуете, что нужно добавить ещё комментариев, подумайте, вероятно нужно переписать такой код, что бы сделать его более понятным.

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

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

5.1 Оформления комментариев реализации

Программа может содержать такие стили комментариев реализации, как: "блочный", "однострочный" или "комментарий в конце строки"

5.1.1 Блочный комментарий

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

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

* Это блочный комментарий

Блочный комментарий начинается с "/*". Оформление тела комментария не должно изменяться. Пример:

* Это блочный комментарий с весьма специфичным

* оформлением, в котором не используются отступы

* один

* два

* три

Замечание: Если вы используете отступы, то и блочный комментарий не используйте или пойдите на уступки чтобы другие могли прибегнуть к идентации вашего кода.

См. также "Документирующий комментарий" на стр. 9.

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

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

if (условие) {

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

...

}

5.1.3 Комментарии в конце строки (блочные)

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

Вот пример кода с блочным комментарием в конце строки (см. также "Документирующие комментарии" на стр. 9)

return TRUE; /* исключение */

return isprime(a); /* только для нечетной a */

5.1.4 Комментарии в конце строки (однострочные)

"//" - знак означающий начало однострочного комментария в плоть до конца строки. Он может занимать всю строку или только ее часть. Не стоит использовать однострочный комментарий для многострочного текста; однако, так можно закомментировать часть кода. Пример всех трех стилей:

// Делаем двойной перевот

return false; // Объясняю почему здесь.

// // Делаем тройной переворот.

5.2 Документирующие комментарии

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

выражение ;

} else if (условие) {

выражение ;

}

выражение;

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

выражение;

}

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

while (условие) {

выражение;

}

while (условие);

do {

выражение;

} while (условие);

switch (условие) {

case ABC:

выражение;

case DEF:

выражение;

break;

case XYZ:

выражение;

break;

default:

выражение;

break;

}

try {

выражение;

} catch (ExceptionClass e) {

Внимание! Этот перевод, возможно, ещё не готов.
Его статус: идёт перевод

Переведено на Нотабеноиде
http://notabenoid.org/book/20188/65826

Переводчики: EugeneL, vapvap14, dimox, kaysen

sabaya, belgita80, NUANN, GlooK

bugagenko, peneksglazami, OctoberHammer

Настройки

Готово:

47.97% КП = 1.2