Соглашения по оформлению кода Java
2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A.
Этот документ защищен авторским правом. Никакая часть этого документа не может быть воспроизведена ни в какой форме, никаким способом без письменного разрешения 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 Зачем нужны соглашения по оформлению кода
2.1 Расширения файлов
2.2 Общие имена файлов
3 Организация файла
3.1 Файлы исходного кода Java
3.1.1 Начальные комментарии
3.1.2 Операторы package и import
3.1.3 Объявление классов и интерфейсов
4.2 Перенос строк
5.1 Форматы комментариев
5.1.1 Блочные комментарии
5.1.2 Однострочные комментарии
5.1.3 Прицепные комментарии
5.1.4 Комментарии до конца строки
5.2 Комментарии для документирования
6.1 Количество объявлений в строке
6.4 Объявление классов и интерфейсов
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.1 Пустые строки
8.2 Расстановка пробелов
9 Соглашение об именовании
10. Приёмы программирования
10.1 Доступ к переменным класса и экземпляра
10.2 Обращение к переменным и методам класса
10.4 Присваивание значений переменным
10.5 Различные приёмы программирования
10.5.2 Возвращаемые значения
10.5.3 Выражения перед "?" в условном операторе
10.5.4 Специальные комментарии
11 Примеры кода
11.1 Пример файла исходного кода Java
Соглашения по оформлению кода Java
1.1 Зачем нужны соглашения по оформлению кода
Соглашения по оформлению кода имеют важное значение для программистов по нескольким причинам:
* 80% от стоимости программного обеспечения приходится на его обслуживание.
* Вряд ли какое-либо программное обеспечение поддерживается в течение всей своей жизни одним автором.
* Соглашения по оформлению кода улучшают читабельность программы, позволяя разработчикам намного быстрее и тщательнее понять новый код.
* Если вы предоставляете свой исходный код как готовую программу, вы должны его хорошо запаковать и очистить, как и остальные программы, которые создаёте.
Этот документ отражает стандарты языка Java, представленные в Java Language Specification, от Sun Microsystems. Основной вклад внесли Питер Кинг, Патрик Ноутон, Майк Демани, Джонни Канерва, Кэти Уолрат и Скот Хоммель.
По вопросам адаптации, модификации или распространение этого документа, пожалуйста, прочтите наше уведомление об авторских правах на http://java.sun.com/docs/codeconv/html/Copyright.doc.html.
Комментарии к этому документу должны быть отправлены нам на форму обратной связи http://java.sun.com/docs/forms/sendusmail.html.
В этом разделе приведены часто используемые имена и расширения файлов
2.1 Расширения имен файлов
Java-программы используют следующие расширения файлов:
Тип файла | Расширение имени файла
2.2 Общие имена файлов
Часто используемые имена файлов включают в себя:
Имя файла | Применение
GNUmakefile | Зарезервированное имя для make-файлов. Мы используем gnumake для сборки нашего программного обеспечения.
README | Зарезервированное имя для текстового файла, содержащего информацию о других файлах в том же каталоге
3 Организация файла
Файл состоит из разделов, которые должны быть разделены пустыми строками и необязательным комментарием, идентифицирующий каждый раздел.
Файлы, в которых больше, чем 2000 строк являются громоздкими и их следует избегать.
Пример правильной организации Java программы см. в разделе "Пример файла исходного кода Java" на стр. 19.
3.1 Файлы исходного кода Java
Каждый файл исходного кода Java содержит один класс с ключевым словом public или интерфейс. Если есть классы с ключевым словом private и интерфейсы, связанные с public классом, то их можно разместить в том же самом исходном файле. Public класс должен быть первым классом или интерфейсом в файле.
Элементы исходного файла Java располагаются в следующем порядке:
* Начальные комментарии (смотрите "Начальные комментарии" на стр. 4)
* Операторы package и import; например:
* Объявление классов и интерфейсов (смотрите "Объявление классов и интерфейсов" на странице 4)
3.1.1 Начальные комментарии
Все файлы исходного кода должны начинаться с комментариев в стиле языка С, где перечислены программист(ы), дата, уведомление об авторских правах, а также краткое описание целей программы. Например:
*Сведения о версии
*Уведомление об авторских правах
3.1.2 Операторы package и import
Первой строчкой кода в большинстве файлов исходных кодов Java является оператор package. После него могут следовать операторы import. Например:
3.1.3 Объявление классов и интерфейсов
Следующая таблица описывает из чего состоит объявление классов или интерфейсов, в том порядке, как они должны появиться. На стр. 19 в разделе "Пример файла исходного кода Java" приведен образец с комментариями.
|Составная часть объявления класса/интерфейса | Примечания
1|Документирующий комментарий класса/интерфейса (/**. */) | Смотрите раздел "Комментарии для документирования" на стр. 9 о том, что должно быть в этом комментарии
2|Оператор class или interface|
3|Если необходимо, то указать комментарий реализации класса/интерфейса (/*. */) | Здесь содержится любая дополнительная информация по классу или интерфейсу, которая не подходит для документирующего комментария.
4|Переменные (поля) класса (статические) | Сначала открытые (public), затем защищенные (protected) и, наконец, закрытые члены класса (private).
5|Переменные (поля) экземпляра |Сначала public, затем protected, после private.
7|Методы | Эти методы должны быть сгруппированы по функциональности, а не по области действия или доступности. Например, закрытый (private) метод класса может находится между двумя открытыми. Цель - сделать проще чтение и ясность кода.
В качестве единицы отступа используется 4 пробела. Точное построение отступов (пробелы или табуляция) не определено. Табуляция должна быть установлена как 8 пробелов (не 4).
Избегайте строки длиннее 80 символов, так как они плохо обрабатываются многими терминалами и инструментами.
Примечание: примеры используемые в документации должны иметь более короткую длину строчек, как правило, не более 70 символов.
4.2 Перенос строк
Если выражение не умещается в одну строку, разбейте его, руководствуясь следующими основными принципами:
* Перенос после запятой
* Перенос перед оператором
* Предпочитаются переносы на более высоком уровне переносам на низком (более вложенном) уровне.
* Выравнивайте новую строку выражения так, чтобы его начало было на том же уровне как и в предыдущей строке.
* Если приведенные выше правила приводят к сбивающему с толку коду или коду, который жмется к полям справа, просто сделайте вместо этого отступ в 8 пробелов.
Несколько примеров переноса строки в вызовах методов:
function(longExpression1, longExpression2, longExpression3,
Следующие два примера демонстрируют разбиение арифметического выражения. Первое предпочтительнее, с разрывом за пределами скобок, расположенных на верхнем уровне.
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; // РЕКОМЕНДУЕТСЯ
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; // ИЗБЕГАТЬ
Два следующих примера иллюстрируют отступы в объявлениях методов. первый случай обычный. Во втором случае следовало бы сдвинуть вторую и третью строки далеко вправо, если бы применялись обычные отступы. Вместо этого строки сдвинуты всего на 8 позиций.
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
//ОТСТУП НА 8 СИМВОЛОВ, ЧТОБЫ ИЗБЕЖАТЬ ОЧЕНЬ ДЛИННЫХ ОТСТУПОВ
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
В условии оператора if следует в основном использовать 8-ми символьный отступ, т.к. если использование 4-х символьного отступа затруднит поиск тела оператора. Рассмотрим пример:
//НЕ ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ
if ((condition1 && condition2)
doSomethingAboutIt(); //ОЧЕНЬ ЛЕГКО ПРОПУСТИТЬ ЭТУ СТРОЧКУ
//ИСПОЛЬЗУЙТЕ ТАКИЕ ОТСТУПЫ В ПОДОБНЫХ СЛУЧАЯХ
if ((condition1 && condition2)
// ИЛИ ИСПОЛЬЗУЙТЕ ЭТО
if ((condition1 && condition2) || (condition3 && condition4)
Вот 3 приемлемых способа форматирования тернарных выражений:
alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
Программа на Java может иметь два вида комментариев: комментарий реализации и документирующий комментарий. Комментарий реализации те же, что и в C++, обозначающиеся /* . */ и //. Документирующие комментарии (известные как "doc comments" или "Javadoc") есть только в Java, и обозначаются /** . */. Javadoc может быть извлечен из кода в HTML файл, используя инструмент javadoc.
Комментарии кода используются для описания отдельных строк/блоков кода или целого алгоритма. Комментарии для документирования используются, чтобы описать спецификацию кода (его интерфейс), не зависящую от его реализации. Комментарии для документирования делают для разработчиков, которые будут использовать ваши программы (библиотеки классов) не имея их исходного кода.
Комментарии нужны, чтобы описать код или пояснить моменты, которые сложно понять непосредственно из кода. Комментарии должны содержать лишь ту информацию, которая необходима для чтения и понимания кода программы. Например информацию о том, как откомпилировать связанный пакет или в какой директории он находится не стоит описывать в комментарии.
Обсуждение нетривиальных или неочевидные решений необходимо, но не нужно описывать то, что и так ясно из кода. Такие "избыточные" комментарии очень быстро могут стать неактуальными. В общем, следует избегать любых комментариев, которые могут стать неактуальными по мере развития кода.
Примечание: большое количество комментариев иногда отражает низкое качество кода. Когда вы чувствуете, что необходимо добавить комментарий, подумайте: может лучше переписать код, чтобы он стал более понятным.
Не стоит делать огромных комментариев, отделенных от основного кода строками из "*" или других символов.Например:/************************************ * Сказание о Мамаевом побоище * ************************************/
Комментарии не должны содержать специальных символов, каких как символ конца страницы или backspace.
Оформление комментариев кода.
В программе можно испольковать 4 вида комментариев кода: бличные, однострочные, прицепные и комментарии до конца строки.
5.1.1 Блочные комментарии
Блочные комментарии используются для предоставления описания файлов, методов, структур данных и алгоритмов. Блочные комментарии следует использовать в начале каждого файла и перед каждым методом. Они также могут быть использованы в других местах, например, внутри методов. Блочные комментарии внутри функции или метода должны иметь отступ на том же уровне, что и код, который они описывают.
Перед блочным комментарием следует оставлять пустую строку, чтобы визуально отделить его от кода. Каждая строка блочного комментария (кроме первой) должна начинаться с символа "*".
* Здесь блок комментариев.
Если блочный комментарий начинатся с "/*-", это означает в данном блоке используется особое форматирование, которое нельзя потерять. (Такой блок не будет переформатирован средствами автоформатирования) Пример:
* Этот блочный комментарий содержит очень специфичное
* форматирование, которое должно игнорироваться средствами автоформатирования
Примечание: Если вы не используете средства автоформатирования, вам не обязательно использовать "/*-" в коде, но можете сделать это на случай того, что кто-то другой может запустить средства автоформатирования на вашем коде.
Смотри также "Комментарии для документирования" на странице 9
5.1.2 Однострочные комментарии
Краткие комментарии можно писать на одной строке используя отступ на уровне соответствующего блока кода. Если комментарий не помещается в одну строку, следует использовать блочный комментарий (см. раздел 5.1.1). Перед однострочным комментарием следует оставлять пустую строку. Вот пример однострочного комментария в Java коде (см. также "Комментарии для документирования» на стр. 9):