Автор: Савченко В.В. ИП-41 Java Code Conventions

↑

▷ Содержание

Стр 1 из 5Следующая ⇒

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

Если в команде разработчиков все будут придерживаться общепринятых правил – использование шаблонов проектирования, одинаковое оформление кода, то им будет легче взаимодействовать, понимать друг другом написанный код, и времени на понимание – “эээ, а что ж тут написано?…” будет затрачено гораздо меньше.

Есть такой документ Code Conventions for the JavaTM Programming Language в котором описано как должен оформляться код. Думаю каждый Java программист должен знать свод этих правил.

JCC важны для программистов из-за целого ряда причин :

• Очень редко программное обеспечение обслуживается в течение всего существования первоначальным автором .

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

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

ОФОРМЛЕНИЕ ФАЙЛА С ИСХОДНЫМ КОДОМ:

ОБЬЯВЛЕНИЕ КЛАССОВ И ИНТЕРФЕЙСОВ:

Тип обьявления

Заметки

Документирующий комментарий класса/интерфейса(/**...*/)

Обьявление class или interface

-

Комментарий к реализации класса/интерфейса(/*...*/), если нужно.

Переменные класса (static)

Сначала переменные public, потом protected, и затем private.

Другие переменные

Сначала переменные public, потом protected, и затем private.

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

-

Методы

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

• Разрыв после запятой .

• Разрыв перед оператором .

• Более предпочтительны разрывы на высшем уровне, чем разрывы на нижних.

• Совместите новую строку с началом выражения на том же уровне, что и на предыдущей

строке.

• Если вышеуказанные правила приведут к путанице кода или к коду, который смещен за правую границу, просто внесите в строку отступ из 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 пробелов, так как иначе 2 и 3 строки в процессе смещения выйдут за границу позволенной длины строки.

someMethod(int anArg, Object anotherArg, String yetAnotherArg,

                  Object andStillAnother) {

      ...

}

private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {

      ...

}

Отступы для выражений if должны состоять из 8 пробелов, иначе будет тяжело разобраться в теле условия.

if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
dоSomethingAboutIt(); …

if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
doSomethingAboutIt(); …

документирующие комментарии . Комментарии реализации такие же как и те, которые содержатся в C ++ , они обычно разграничены /*...*/ , и //. Документирующие комментарии (известные как " Javadoc " ) свойственны только Java и ограничиваются /**...*/ . Такие комментарии могут быть извлечены в HTML файлы с помощью инструмента Javadoc .

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

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

комментарии.

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

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

ОБЬЯВЛЕНИЯ:

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

int level; // indentation level

int size; // size of table

Не пишите обьявления разных типов в одну строку и также не обьявляйте переменные и функции в общей строке. Так не надо делать:

long dbaddr, getDbaddr();

int foo, fooarray[];

В вышеуказанных примерах между типом и именем стоит пробел, еще один способ правильно обьявить данные, это использовать табы:

int          level;         // indentation level

int          size;            // size of table

Object currentEntry; // currently selected table entry

ПУСТЫЕ СТРОКИ:

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

Две пустые строки должны всегда быть между секциями исходного файла и определениями классов и интерфейсов.

Одна пустая строка всегда должна быть:

• Между методами

• Между локальными переменными в методе и их первым обьявлением.

• Перед блоком или одиночным комментарием.

• Между логическими разделами внутри метода для улучшения читаемости.

СОГЛАШЕНИЯ ОБ ИМЕНОВАНИИ:

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

Тип идентификатора

Правила именования

Примеры

Класс

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

Старайтесь, чтобы ваши имена классов были простыми и имели описательный характер. Используйте полные слова - избегайте

сокращений и аббревиатур.

class Raster;

class ImageSprite;

Интерфейс

Аналогично с именами классов.

interface RasterDelegate; interface Storing;

Методы

Имена методов должны быть глаголами.

Первая буква в нижнем регистре, а первые буквы

каждого внутреннего слова заглавные.

run();

runFast();

 getBackground();

Переменные

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

int   i;

char    cp;

float myWidth;

Константы

Имена констант в в классе записываются в формате заглавных букв с нижним подчеркиванием для разделения.

int MIN_WIDTH = 4;

int MAX_WIDTH = 999;

int GET_THE_CPU = 1;

Познавательные статьи:



Техника прыжка в длину с разбега

Организация работы процедурного кабинета

Области применения синхронных машин

Оптимизация по Винеру и Калману