Требования к организации и оформлению кода (Java)¶

Указания по редактированию данного документа¶

На редактирование следует открывать минимальную по размерам часть документа (нажимать на соответствующую иконку с карандашом).

Предложения по изменению документа следует обрамлять тэгами

Соглашения об именах¶

1. Имена должны быть осмысленными словами (или словосочетаниями в значении соответствующей части речи) английского языка.

2. Имена пакетов и подпакетов — существительные в единственном числе в нижнем регистре, слова разделяются подчёркиваниями (program_installer).

3. Имена классов и интерфейсов — существительные или словосочетания в значении существительных: в нижнем регистре, первые буквы слов — в верхнем регистре, разделители слов не используются (ClientInfo); имена классов-исключений заканчиваются на Exception (InvalidUserException).

4. Рекомендуется для классов-наследников использовать имена, в которых содержится имя суперкласса (ModalDialog extends Dialog); исключение — имена классов-наследников, из которых следует, что данный класс наследует суперкласс (Triangle extends Figure).

5. Имена полей̆ и локальных переменных — существительные в нижнем регистре, первые буквы слов начиная со второго — в верхнем регистре, разделители слов не используются (fileSize).

6. Имена полей и локальных переменных не должны вводить в заблуждение относительно их типов. Пример (!) НЕПРАВИЛЬНОГО (!) именования переменной: String currentPlayer = player.getName();

7. Имена методов — глаголы в нижнем регистре (либо словосочетания, отражающие действия), первые буквы слов начиная со второго — в верхнем регистре, разделители слов не используются (removeFile).

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

9. Имена методов, выполняющих чтение/изменение значений полей класса, должны начинаться на get и set, соответственно (getFileAttr, setFileAttr); исключение — методы, возвращающие значения полей типа boolean, они начинаются на is (isOk).

10. Имена методов, выполняющих преобразование к другому типу данных, должны начинаться на to (toString).

11. Имена методов, которые создают и возвращают созданный объект, должны начинаться с create (createRecord).

12. Имена методов, инициализирующие поля класса или элементы графического интерфейса, должны начинаться с init (initWindow) и использоваться только в конструкторе класса. Таких методов следует избегать.

13. Имена static final переменных — существительные или словосочетания в верхнем регистре, слова разделены подчёркиваниями (INVALID_RECORD_COLOR).

Требования к отдельным деталям реализации¶

1. Запрещается использование вложенных классов. Исключение - вложенные классы, заменяющие анонимные классы с несколькими методами.

2. Тело метода анонимного класса должно состоять только из вызова метода объемлющего класса.

3. Все элементы программы должны иметь минимально возможную область видимости.

4. Аргументы, передаваемые в методы, не должны изменяться внутри этих методов.

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

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

7. Запрещается секционирование методов. Секционирование означает, что метод можно разделить на несколько.

8. Методы, изменяющие состояние объекта, не должны возвращать статус этой операции (например, метод insert(object) должен выполнять только операцию вставки и не должен возвращать статус этой операции).

9. Не рекомендуется возвращать какие-либо значения из методов, изменяющих состояния объекта.

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

11. Запрещается собственная реализация средств, имеющих аналоги в стандартной библиотеке Java API. Во всех случаях, когда возможно использование библиотечных классов Java API, они должны быть использованы.

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

13. Запрещается посимвольная обработка строковых данных в стиле языка C. Вместо этого необходимо использовать средства стандартной библиотеки.

14. Запрещается использование средств библиотек, обозначенных в документации как deprecated (устаревшие).

15. Нежелательно использование средств библиотек, обозначенных в документации как legacy (для обратной совместимости).

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

17. Запрещается импортирование всех элементов, содержащихся в пакете (import *)/vxvv

Требования по оформлению исходного текста программы¶

1. Исходный текст каждого класса программы должен быть размещён в отдельном файле (кроме вложенных классов).

2. Пустые строки внутри класса должны быть только между методами. Порядок следования элементов класса следующий: поля, конструкторы, методы. Пример:

public class Rectangle {
    /** First side length of the rectangle.*/
    private x;
    /** Second side length of the rectangle.*/
    private y;

    /**
     * Constructor.
     * @param x First side length of the rectangle.
     * @param y Second side length of the rectangle.
     */
    public Rectangle (x, y) {
        this.x = x;
        this.y = y;
    }

    /**
     * Constructs square.
     * @param x Side length of the square.
     */
    public Rectangle :x: {
        this.x = x;
    }

    /**
     * Returns whether this rectangle is a square.
     * @returns True if this rectangle is a square and false otherwise.
     */
    public boolean isSquare () {
        return x==y;
    }

   /**
     * Returns the area of the rectangle.
     * @returns The area of the rectangle.
     */
    public int getArea () {
        return x*y;
    }
}

1. Программы должны быть выровнены в соответствии со стилем Кёрнигана и Ричи.

2. Величина отступа всюду должна быть 4 пробела. Запрещается использовать символ табуляции.

3. Все операторы линейной части программы должны иметь один и тот же отступ. Отступ увеличивается для объявлений вложенных классов, полей и методов классов, тел методов, субоператоров (в т. ч. для всех операторов блока, образующего субоператор).

4. При использовании множественного ветвления обязательно следует размещать конструкции else if строго друг под другом без дополнительных отступов.

5. Точка с запятой, завершающая пустой оператор, должна размещаться на отдельной строке.

6. Не допускается использование строк, длина которых больше 95 символов. Не вмещающиеся части строки переносятся на следующие строки с отступом относительно предыдущей строки. Рекомендуется использовать отступ вдвое больше определённого для программы. Перенос строк, содержащих объявление метода, допускается осуществлять без отступа.

7. Запрещается перенос аргументов метода в стиле WIN32, т. е. когда каждый аргумент располагается на новой строке. Пример:

public void insertElements(begin,
                           end,
                           elements)

1. Запрещается размещение нескольких операторов в одной строке, кроме случаев, когда это не ухудшает удобочитаемости программы.

2. Разрешается написание одной строкой условного оператора, в теле которого содержится всего один вызов return. Пример:

if (x > 0) return x;

1. Рекомендуется использование пробелов для отбивок отдельных лексем в программе. Способ расстановки пробелов в этом случае должен соответствовать полиграфическим правилам.

2. Многострочный документационный комментарий выравнивается следующим образом: первая и последняя строки содержать только символы /** и */ (или **/) соответственно. Все промежуточные строки начинаются со звёздочки, за которой следует текст комментария.

Требования по документированию программы¶

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

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

3. В случае использования меток в операторах break и continue обязательно наличие комментария в строке, содержащей один из указанных операторов.

4. Комментарии не должны содержать орфографических и пунктуационных ошибок.

5. В случае, если комментарий к полю класса начинается с существительного, перед ним должен стоять артикль The.

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

Android-специфичные требования¶

1. Следует избегать использования findViewById() в коде. Если к компоненту необходим доступ, следует создать поле со спецификатором final и записать туда ссылку на компонент. Запрещается создавать методы, единственным действием которых является вызов findViewById().

Дополнительные требования, не имеющие прямого отношения к непосредственно Java коду¶

• Требования к оформлению XML.