ROS code style

Стиль написания кода

В этой статье изложены основные принципы стилизации написания исходного кода, которых необходимо придерживаться при написании нового кода для проекта ReactOS. Всё, что написано в этой статье, применимо лишь к коду, написанному на языках C и C++. Участники проекта огласились с этим документом на собрании разработчиков, проходившем в октябре 2013 года.

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

Код, взятый из посторонних источников (например Wine), переписывать не нужно.

Структура файлов

1.Каждый файл исходного кода ReactOS должен иметь заголовок наподобие этого:

/*
 * PROJECT:        ReactOS Kernel
 * LICENSE:        GNU GPLv2 only as published by the Free Software Foundation
 * PURPOSE:        Does cool things like ...
 * PROGRAMMERS:    Arno Nymous (abc@mailaddress.com)
 *                 Mike Blablabla (mike@blabla.com)
 */

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

Примеры:

• GNU GPLv2 only as published by the Free Software Foundation
• GNU GPLv2 or any later version as published by the Free Software Foundation
• BSD - See COPYING.ARM in the top-level directory

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

2.Для функций используйте заголовок наподобие приведённого ниже:

/**
 * @name SomeAPI
 * @implemented
 *
 * Do nothing for 500ms.
 *
 * @param SomeParameter
 * Description of the parameter.
 *
 * @param YetAnotherParameter
 * Bleh, bleh :)
 *
 * @return
 * STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
 * otherwise.
 *
 * @remarks Must be called at IRQL == DISPATCH_LEVEL
 *
 */

Отступы

1. Делайте отступ при помощи 4 пробелов, не используйте табуляцию!
2. Делайте отступ и для case и для его операндов.

Верно:

switch (Condition)
{
    case 1:
        DoSomething();
        break;
}

Неверно:

switch (Condition)
{
case 1:
     DoSomething();
     break;
}

Пробелы

1.Не используйте пробелы до и после унарных операторов.

Верно: i++;

Неверно: i ++;

2.Вставляйте пробелы вокруг двойных и тройных операторов.

Верно: a = b + c;

Неверно: a=b+c;

3.Не ставьте пробелы перед запятой и точкой с запятой.

Верно:

for (int i = 0; i < 5; i++)
    DoSomething();
 
func1(a, b);

Неверно:

for (int i = 0 ; i < 5 ; i++)
    DoSomething();
 
func1(a , b) ;

4.Добавляйте пробелы между управляющими операторами и скобками.

Верно:

if (Condition)
    DoSomething();

Неверно:

if(Condition)
    DoSomething();

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

Верно:

func(a, b);

Неверно:

func (a, b);
func( a, b );

Переносы строк

1.Каждый оператор должен находиться на отдельной строке.

Верно:

x++;
y++;
 
if (Condition)
    DoSomething();

Неверно:

x++; y++;
 
if (Condition) DoSomething();

Скобки

1. Всегда делайте так, чтобы скобки ({ и }) находились на отдельных строках.

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

Верно:

if (Condition)
    DoSomething();
 
if (Condition)
{
    DoSomething();
}
 
if (Condition)
{
    // This is a comment
    DoSomething();
}
 
if (Condition)
    DoSomething();
else
    DoSomethingElse();
 
if (Condition)
{
    DoSomething();
}
else
{
    DoSomethingElse();
    YetAnother();
}

Неверно:

if (Condition) {
    DoSomething();
}
 
if (Condition)
    // This is a comment
    DoSomething();
 
if (Condition)
    DoSomething();
else
{
    DoSomethingElse();
    YetAnother();
}

Управляющие структуры

1.Не используйте обратную логику.

Верно:

 if (i == 1)

Неверно:

 if (1 == i)

2.Избегайте слишком большой вложенности структур управления. Предпочтительнее использовать “линейный вид” а не “древообразный вид”. Используйте goto, если это поможет улучшить читаемость кода.

Верно:

if (!func1())
    return;
 
i = func2();
if (i == 0)
    return;
 
j = func3();
if (j == 1)
    return;
…

Неверно:

if (func1())
{
    i = func2();
    if (func2())
    {
        j = func3();
        if (func3())
        {
            …
        }
    }
}

Именование

1.Пишите имена переменных и функций с большой буквы.

При разработке для Win32 можно использовать венгерскую нотацию, однако это не обязательное требование. Если вы решили не использовать её, то первая буква тоже должна быть в верхнем регистре (а не camelCase). Не используйте в качестве разделителей символы нижнего подчёркивания.

Верно:

PLIST_ENTRY FirstEntry;
VOID NTAPI IopDeleteIoCompletion(PVOID ObjectBody);
PWSTR pwszTest;

Неверно:

PLIST_ENTRY first_entry;
VOID NTAPI iop_delete_io_completion(PVOID objectBody);
PWSTR pwsztest;

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

3.Если это возможно и подходит по смыслу, то перед именами булевых переменных пишите глаголы, помогающие легко понять их назначение, напр. "is" и "did".

Верно:

BOOLEAN IsValid;
BOOLEAN DidSendData;

Неверно:

BOOLEAN Valid;
BOOLEAN SentData;

Добавление комментариев

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

Верно:

// Это однострочный комментарий
 
/* Это комментарий в стиле C */
 
//
// Это комментарий на несколько строк.
// Для его оформления у нас нет строгих правил.
//

Неверно:

//
// В этом комментарии две строчки остаются неиспользованными
//

Null, false и 0

1.Нулевой указатель должен быть написан как NULL.

В редких случаях когда ваша среда разработки рекомендует использовать другой нулевой указатель (напр. nullptr в C++11), разумеется, нужно использовать его.

Просто не используйте значение 0.

2.Булевы значения в Win32/NT должны быть написаны как TRUE и FALSE.

В редких случаях при использовании переменных bool в C/C++, вы должны писать их как true и false.

Примечания по переформатированию существующего кода

• Никогда одновременно не занимайтесь переформатированием кода и добавлением в него изменений. Сделайте это в отдельных коммитах.
• Если в коммит входят лишь изменения в форматировании кода, в явном виде обозначьте это в сообщении коммита при помощи метки [FORMATTING].

Использование инструментария для автоматической стилизации кода

TO BE ADDED BY User:Zefklop

Отклонённые предложения по форматированию

Во время обсуждения этого документа было высказано ещё несколько идей оформления кода, однако по ним не был достигнут консенсус. Поэтому мы пока воздержимся от настойчивого требования соблюдения этих правил:

TO BE ADDED BY User:Hbelusca

Дополнительная информация

• GNU Indent