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

var = function1(longExpression1,

sabaya 03.09.11 в 14:47

function2(longExpression2,

sabaya 03.09.11 в 14:47

longExpression3));

sabaya 03.09.11 в 14:47

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

sabaya 03.09.11 в 14:49

longName1 = longName2 * (longName3 + longName4 - longName5)

sabaya 03.09.11 в 14:50

+ 4 * longname6; // Лучше

sabaya 03.09.11 в 14:50

longName1 = longName2 * (longName3 + longName4

sabaya 03.09.11 в 14:50

- longName5) + 4 * longname6; // Хуже

sabaya 03.09.11 в 14:50

Далее приведены два примера переноса строк в определении метода. Первый использует соглашения. Во втором использование соглашений привело бы к тому, что вторая и третья строка были бы слишком сдвинуты вправо, поэтому используется только отступ в 8 пробелов.

sabaya 03.09.11 в 14:59

// СОГЛАШЕНИЕ ПО ОТСТУПАМ

EugeneL 15.01.12 в 13:29

someMethod(int anArg, Object anotherArg, String yetAnotherArg,

EugeneL 15.01.12 в 13:29

Object andStillAnother) {

EugeneL 15.01.12 в 13:29

...

EugeneL 15.01.12 в 13:29

}

EugeneL 15.01.12 в 13:29

// ДЕЛАЙТЕ ОТСТУП В 8 СИМВОЛОВ ДЛЯ ИЗБЕЖАНИЯ ГЛУБОКОЙ ВЛОЖЕННОСТИ

EugeneL 15.01.12 в 13:30

private static synchronized horkingLongMethodName(int anArg,

EugeneL 15.01.12 в 13:30

Object anotherArg, String yetAnotherArg,

EugeneL 15.01.12 в 13:30

Object andStillAnother) {

EugeneL 15.01.12 в 13:30

...

EugeneL 15.01.12 в 13:30

}

EugeneL 15.01.12 в 13:30

Оформление строк для выражения if должно использовать 8-символьный отступ, т.к. использование стандартного (4-символьного) затрудняет просмотр тела выражения. Например:

EugeneL 15.01.12 в 13:35

// ТАК ОТСТУПЫ ДЕЛАТЬ НЕЛЬЗЯ

EugeneL 15.01.12 в 13:31

if ((condition1 && condition2)

EugeneL 15.01.12 в 13:31

|| (condition3 && condition4)

EugeneL 15.01.12 в 13:31

||!(condition5 && condition6)) { //ПЛОХОЕ ОФОРМЛЕНИЕ

EugeneL 15.01.12 в 13:31

doSomethingAboutIt(); // ПОЗВОЛЯЕТ ЛЕГКО ПРОПУСТИТЬ ЭТУ СТРОКУ

EugeneL 15.01.12 в 13:32

}

EugeneL 15.01.12 в 13:32

// ЛУЧШЕ ОТСТУПЫ ДЕЛАТЬ ВОТ ТАК

EugeneL 15.01.12 в 13:36

if ((condition1 && condition2)

EugeneL 15.01.12 в 13:36

|| (condition3 && condition4)

EugeneL 15.01.12 в 13:36

||!(condition5 && condition6)) {

EugeneL 15.01.12 в 13:37

doSomethingAboutIt();

EugeneL 15.01.12 в 13:37

}

EugeneL 15.01.12 в 13:37

// ИЛИ ВОТ ТАК

EugeneL 15.01.12 в 13:37

if ((condition1 && condition2) || (condition3 && condition4)

EugeneL 15.01.12 в 13:37

||!(condition5 && condition6)) {

EugeneL 15.01.12 в 13:37

doSomethingAboutIt();

EugeneL 15.01.12 в 13:37

}

EugeneL 15.01.12 в 13:37

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

EugeneL 15.01.12 в 13:38

alpha = (aLongBooleanExpression) ? beta : gamma;

EugeneL 15.01.12 в 13:38

alpha = (aLongBooleanExpression) ? beta

EugeneL 15.01.12 в 13:38

: gamma;

EugeneL 15.01.12 в 13:38

alpha = (aLongBooleanExpression)

EugeneL 15.01.12 в 13:38

? beta

EugeneL 15.01.12 в 13:38

: gamma;

EugeneL 15.01.12 в 13:38

5 Примечаний

EugeneL 15.01.12 в 13:39

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

kaysen 19.09.11 в 19:29

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

EugeneL 15.01.12 в 13:40

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

kaysen 19.09.11 в 19:31

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

kaysen 19.09.11 в 19:32

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

kaysen 19.09.11 в 19:34