Coding Guidelines

1 Отступы и форматирование

1.1 Стиль форматирования

1.1.1 Базовый стандарт оформления кода: Kernighan & Ritchie (K&R)

1.1.2 Данный стиль использует стиль расстановки скобок, при котором скобка переносится на новую строку при определении пространств имен (namespaces), классов (classes), в остальных случаях скобка остается на той же строке, где располагается часть кода, к которой она (скобка) принадлежит.

1.1.3 Отступ в данном стиле равняется 4-м пробелам.

Пример:

    // правильно
    int foo(int isBar) {
        if (isBar) {
            bar();
            return 1;
        } else {
            return 0;
        }
    }

    // неправильно
    int foo(int isBar) 
    {
	    if (isBar) 
	    {
	    bar();
	    return 1;
	    } 
	    else 
	    {
	    return 0;
	    }
    }

1.1.4 Используйте пробелы для группировки отдельных сегментов кода.

1.1.5 Две пустых линии используются, чтобы разделить объявления классов и интерфейсов.

1.1.6 Одна пустая линия должна разделять:

• Методы

• Локальные переменные в методе и первое выражение

• Блок или отдельную строку комментариев

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

1.2 Форматирование строк, длина операторов/выражений

1.2.1 Старайтесь не превышать длину строки в 80 символов. Если аргументы метода не помещаются на одной строке, их следует разбивать на несколько строк.

Пример:

    // правильно
    int lotsOfArgs(int aInteger, long aLong, short aShort, 
                     double aDouble, float aFloat);

    // неправильно 
    int lotsOfArgs(int aInteger, long aLong, short aShort, double aDouble, float aFloat);

1.2.2 В сложных выражениях размещайте каждое условие на отдельной строке.

Пример:

    // правильно
    if ((('0' <= inChar) && (inChar <= '9'))
            ||  (( 'а' <= inChar) && (inChar <= 'z'))
            ||  (( 'A' <= inСhar) && (inСhar <= 'Z'))) {
        /* .... */
    }

    // неправильно
    if ((('0' <= inChar) && (inChar <= '9')) || (( 'а' <= inChar) && (inChar <= 'z')) || (( 'A' <= inСhar) && (inСhar <= 'Z'))) {
        /* .... */
    }

1.2.3 Всегда располагайте один оператор на строке.

Пример:

    // правильно
    a = b + 1;
    c++;

    // неправильно
    a = b + 1; c++;

1.3 Операторы if/else, do, while, for

Пример:

    if (x < foo(y, z)) {
       /* Body */
    }

1.3.1 Расставляйте скобки так, чтобы не было "висячих" операторов else, лучше всегда выделять скобками блоки кода, даже когда скобки могут быть опущены.

1.3.2 else if следует писать так:

Пример:

    if (x == y) {
        ...
 
    } else if (x > y) {
        ...
 
    } else {
        ...
 
    }

1.3.3 do / while следует писать так:

Пример:

    do {
    ...
 
    } while (condition);

1.3.4 for следует писать так:

Пример:

    for (initialization; condition; update) {
        statements; 
    }

1.4 Условия множественного выбора switch

1.4.1 Операторы case должны находиться в той же колонке, что и оператор switch.

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

Пример:

    switch (MyEnum) {
    case VALUE1:
        doSomething();
        break;
    case VALUE2:
    case VALUE3:
        doSomethingElse();
        // fall through
    default: defaultHandling();
    break;
    }

1.5 Выражение типа try-catch

1.5.1 Выражение типа try-catch должно иметь следующий вид.

Пример:

    try {
        statements;
    } catch (ExceptionClass e) {
        statements;
    }

1.6 Операции

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

Пример:

    //правильно
    if (i == 0) {
        break;
    }
    a += 3;
    a = b + c;

    //неправильно
    if (i = = 0) {
        break;
    }
    a+ =3;
    a=b+c;

1.6.2 Не оставлять пробела после унарной операции.

Пример:

    if (!flag) {
        break;
    }

2 Выбор имен

2.1.1 Все названия должны быть на английском.

2.1.2 Названия пакетов должны быть написаны строчными буквами.

Пример:

    mypackage, com.company.application.ui

2.1.3 Названия классов должны быть существительными и написаны в PascalCase.

Пример:

    class Raster;
    class ImageSprite;

2.1.4 Интерфейсы должны быть в PascalCase.

Пример:

    interface RasterDelegate;
    interface Storing;

2.1.5 Названия методов должны быть глаголами и написаны в camelCase.

Пример:

    run();
    runFast();
    getBackground();

2.1.6 Имена переменных должны быть в camelCase. Дождитесь, пока переменная будет нужна, и только тогда объявляйте ее. Старайтесь избегать однобуквенных имен, за исключением временных «ненужных» переменных (для них используйте буквы i, j, k, m, n для int и c, d, e для char).

Пример:

    float myWidth;
    int i;

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

Пример:

    int MIN_WIDTH = 4;
    int MAX_WIDTH = 999;
    int GET_THE_CPU = 1; 

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

Пример:

    enum Season { 
        WINTER, SPRING, SUMMER, AUTUMN
    }

2.1.9 Следует избегать аббревиатур, кроме случаев, где аббревиатура более известна, чем полное название. Аббревиатуры должны быть в camelCase.

Пример:

    exportHtmlSource();

2.1.10 Префикс Is следует использовать в названиях переменных и методах типа Boolean.

Пример:

    isSet, isVisible, isFinished, isFound, isOpen;

2.1.11 Следует использовать compute в методах, где подсчитывается какое-то значение, find – в методах, где что-то ищется.

Пример:

    valueSet.computeAverage();
    matrix.computeInverse()
 
    vertex.findNearestVertex();
    matrix.findSmallestElement();
    node.findShortestPath(Node destinationNode);

2.1.12 Используйте множественное число для коллекций объектов.

Пример:

    Collection<Point> points;
    int[] values;

2.1.13 Избегайте отрицательных префиксов для переменных и методов типа boolean.

Пример:

    //правильно
    bool isError; 
    bool isFound; 

    //неправильно
    bool isNoError;
    bool isNotFound;

3 Объявление

3.1 Классы и интерфейсы

3.1.1 Классы и интерфейсы должны объявляться следующим образом:

• Статические переменные класса в порядке public, protected, package (no access modifier), private

• Остальные переменные класса в порядке public, protected, package (no access modifier), private

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

• Методы

3.2 Методы

3.2.1 Модификаторы метода должны идти в следующем порядке: static abstract synchronized final native.

Пример:

    //правильно
    public static double square(double a);  

    //неправильно
    static public double square(double a);

3.3 Типы

3.3.1 Приведение типов следует писать в явном виде.

Пример:

    //правильно
    floatValue = (int) intValue;

    //неправильно
    floatValue = intValue;

3.3.2 Массивы следует объявлять скобками рядом с типом.

Пример:

    //правильно
    double[] vertex;  
    int[] count;   

    //неправильно
    double vertex[];
    int count[];

4 Комментирование

4.1.1 Все комментарии следует писать на английском языке.

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

4.1.3 Блоки и отдельные строки комментариев должны быть сдвинуты так же, как и окружающий их код. Можно использовать различные формы записи комментариев.

Пример:

    /*
     * comment
     */
 
    // very long
    // comment
 
    /*
     * another comment */

4.1.4 Используйте комментарии TODO для кода, который является временным, краткосрочным, или хорошим, но не идеальным. Также следует вставлять конкретную дату, к которой проблема должна быть решена, или же конкретное событие (например, "Удалить после выхода версии 2.1")

Пример:

    // TODO: Change this to use flag instead of constant

4.2 JavaDoc

4.2.1 Каждый класс и public метод должен содержать Javadoc, по крайней мере, с одной фразой, описывающей, что он делает. Фраза должна начинаться с описательного глагола 3-го лица.

Пример:

    /** Returns the correctly rounded positive square root of a double value. */
    static double sqrt(double a) {
    }
 
    /**
     * Constructs a new String by converting the specified array of 
     * bytes using the platform's default character encoding.
     */
    public String(byte[] bytes) {
    }

4.2.2 Вам не нужно описывать Javadoc для тривиальных get и set методов, таких как setFoo(), если ваш Javadoc говорит только «sets Foo». Если метод делает что-то более сложное (например, соблюдение неких ограничений, или если его действия имеют важный эффект вне его самого), тогда его обязательно нужно задокументировать. И если это не просто объяснение того, что означает Foo, то вам также следует его задокументировать.

4.2.3 Для документирования можно использовать дескрипторы:

@author — автор

@version — версия

@since — указывает с какой версии появился этот блок кода

@see — ссылка на другое место в документации

@param — передаваемый параметр методу

@return — описание возвращаемого значения метода

@exception и @throws — описание исключений

@deprecated — документирование устаревших частей кода

{@link} — создание ссылки, можно вставлять в любое место

{@value} — описание значения переменной

Пример:

    /** Класс служит для хранения объектов со свойствами
     * <b>maker</b> и <b>price</b>.
     * @autor Filippov Yakov
     * @version 1.0
    */
    class Product
    {
            /** Свойство - производитель */
            private String maker;
 
            /** Свойство - цена */
            public double price;
 
            /** Создает новый пустой объект
             * @see Product#Product(String, double)
            */
            Product(){
                    setMaker("");
                    price=0;
            }
 
            /** Создает новый объект с заданными значениями
             * @param maker - производитель
             * @param price - цена
             * @see Product#Product()
            */
            Product(String maker,double price){
                    this.setMaker(maker);
                    this.price=price;
            }
 
            /** Функция для получения значения поля {@link Product#maker}
             * @return Возвращает название производителя
             */
            public String getMaker() {
                    return maker;
            }
 
            public void setMaker(String maker) {
                    this.maker = maker;
            }
    }

4.2.4 В документации можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и через символ "#" его метод или поле.

5 Дополнительно

5.1.1 Короткие методы: не пишите гигантских методов.

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

5.1.3 Локальные переменные: ограничивайте область видимости.

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

Пример:

    //правильно
    private static final int TEAM_SIZE = 11;
    Player[] players = new Player[TEAM_SIZE]; 

    //неправильно
    Player[] players = new Player[11];

5.1.5 Следует использовать аннотацию @Override, если метод переопределен.

Пример:

    @Override
        public void speak() { 
           System.out.println("Meow."); 
        }

5.1.6 Избегайте использования goto.

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

Пример:

    //правильно
    Changed main page background picture
    Added button “Set” to the main page

    //неправильно
    I have added new button and that picture with a tree on the main page