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

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

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

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

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

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

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

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

 

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

Файл состоит из разделов, которые должны быть разделены пустыми строками и иметь дополнительные обьясняющие комментарии идентификации каждого раздела.Файлы больше, чем 2000 строк громоздки и их следует избегать . Каждый исходный файл Java содержит один public класс или интерфейс. Когда private классы и интерфейсы связанны с public классом, вы можете поместить их в исходном файле public класса . Public класс должeн быть первым классом или интерфейсом в файлe. Исходные файлы Java имеют следующий порядок :• Начальные комментарии • Отчетность об импорте и упаковке; например:import java.applet.Applet; import java.awt.*; import java.net.*;• Обьявление классов и интерфейсов НАЧАЛЬНЫЕ КОММЕНТАРИИ:Все исходные файлы должны начинаться с комментария в стиле С, в котором перечислена информация о программисте(ах), дате создания продукта, уведомление об авторских правах , а также краткое описание целей программы . Например:/* * Classname * * Version info * * Copyright notice */

 

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

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

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

Заметки

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

 

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

-

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

Этот комментарий должен содержать любую информацию о классе/интерфейсе в целом, которую невозможно было включить в документирующий комментарий.

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

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

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

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

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

-

Методы

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

 

ОТСТУПЫ:
Четыре пробела должны быть использованы в качестве единицы отступа . Точное построение отступа(пробелы против табуляции) не определено . Табы должны быть установлены ровно каждые 8 ​​пробелов (не 4 ) .

 

ДЛИНА СТРОК:
Избегайте строк длиннее 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 пробелов, так как иначе 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(); …

КОММЕНТАРИИ:
Java программы могут иметь два вида комментариев : комментарии реализации и

документирующие комментарии . Комментарии реализации такие же как и те, которые содержатся в 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;