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

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

kaysen 19.09.11 в 19:38

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

kaysen 19.09.11 в 19:39

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

kaysen 19.09.11 в 19:39

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

EugeneL 15.01.12 в 14:32

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

EugeneL 15.01.12 в 14:34

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

EugeneL 15.01.12 в 14:15

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

EugeneL 15.01.12 в 14:18

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

EugeneL 15.01.12 в 14:21

/*

EugeneL 15.01.12 в 14:21

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

EugeneL 15.01.12 в 14:21

*/

EugeneL 15.01.12 в 14:21

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

EugeneL 15.01.12 в 14:38

/*

EugeneL 15.01.12 в 14:38

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

EugeneL 15.01.12 в 14:38

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

EugeneL 15.01.12 в 14:39

*

EugeneL 15.01.12 в 14:39

* один

EugeneL 15.01.12 в 14:39

* два

EugeneL 15.01.12 в 14:39

* три

EugeneL 15.01.12 в 14:39

*/

EugeneL 15.01.12 в 14:39

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

NUANN 15.01.12 в 15:05

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

EugeneL 15.01.12 в 14:22

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

EugeneL 15.01.12 в 13:55

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

NUANN 15.01.12 в 14:59

if (условие) {

EugeneL 15.01.12 в 13:55

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

EugeneL 15.01.12 в 13:55

...

EugeneL 15.01.12 в 13:55

}

EugeneL 15.01.12 в 13:55

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

NUANN 15.01.12 в 16:15

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

NUANN 15.01.12 в 16:29

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

NUANN 15.01.12 в 16:31

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

NUANN 15.01.12 в 15:31

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

NUANN 15.01.12 в 15:35

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

NUANN 15.01.12 в 16:16

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

NUANN 15.01.12 в 16:46

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

NUANN 15.01.12 в 16:48

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

NUANN 15.01.12 в 16:50

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

NUANN 15.01.12 в 16:51