Просмотр исходного текста страницы ROS code style

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

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

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

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

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

<pre>
/*
 * 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)
 */
</pre>

Нам необходимо выдерживать согласованность и убедиться, что указанные в заголовке лицензии могут быть однозначно идентифицированы. Не забывайте, что некоторые лицензии могут быть 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.Для функций используйте заголовок наподобие приведённого ниже:
<pre>
/**
 * @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
 *
 */
</pre>

==Отступы==

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

'''Верно:'''
<pre>
switch (Condition)
{
    case 1:
        DoSomething();
        break;
}
</pre>

'''Неверно:'''
<pre>
switch (Condition)
{
case 1:
     DoSomething();
     break;
}
</pre>

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

'''Верно:''' i++;

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

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

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

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

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

'''Верно:'''
<pre>
for (int i = 0; i < 5; i++)
    DoSomething();
 
func1(a, b);
</pre>

'''Неверно:'''
<pre>
for (int i = 0 ; i < 5 ; i++)
    DoSomething();
 
func1(a , b) ;
</pre>

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

'''Верно:'''
<pre>
if (Condition)
    DoSomething();
</pre>

'''Неверно:'''
<pre>
if(Condition)
    DoSomething();
</pre>

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

'''Верно:'''
<pre>
func(a, b);
</pre>

'''Неверно:'''
<pre>
func (a, b);
func( a, b );
</pre>

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

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

'''Верно:'''
<pre>
x++;
y++;
 
if (Condition)
    DoSomething();
</pre>

'''Неверно:'''
<pre>
x++; y++;
 
if (Condition) DoSomething();
</pre>

==Скобки==

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

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

'''Верно:'''
<pre>
if (Condition)
    DoSomething();
 
if (Condition)
{
    DoSomething();
}
 
if (Condition)
{
    // This is a comment
    DoSomething();
}
 
if (Condition)
    DoSomething();
else
    DoSomethingElse();
 
if (Condition)
{
    DoSomething();
}
else
{
    DoSomethingElse();
    YetAnother();
}
</pre>

'''Неверно:'''
<pre>
if (Condition) {
    DoSomething();
}
 
if (Condition)
    // This is a comment
    DoSomething();
 
if (Condition)
    DoSomething();
else
{
    DoSomethingElse();
    YetAnother();
}
</pre>

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

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

'''Верно:'''
  if (i == 1)
'''Неверно:'''
  if (1 == i)

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

'''Верно:'''
<pre>
if (!func1())
    return;
 
i = func2();
if (i == 0)
    return;
 
j = func3();
if (j == 1)
    return;
…
</pre>

'''Неверно:'''
<pre>
if (func1())
{
    i = func2();
    if (func2())
    {
        j = func3();
        if (func3())
        {
            …
        }
    }
}
</pre>

==Именование==

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

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

'''Верно:'''
<pre>
PLIST_ENTRY FirstEntry;
VOID NTAPI IopDeleteIoCompletion(PVOID ObjectBody);
PWSTR pwszTest;
</pre>

'''Неверно:'''
<pre>
PLIST_ENTRY first_entry;
VOID NTAPI iop_delete_io_completion(PVOID objectBody);
PWSTR pwsztest;
</pre>

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

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

'''Верно:'''
<pre>
BOOLEAN IsValid;
BOOLEAN DidSendData;
</pre>

'''Неверно:'''
<pre>
BOOLEAN Valid;
BOOLEAN SentData;
</pre>

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

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

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

'''Неверно:'''
<pre>
//
// В этом комментарии две строчки остаются неиспользованными
//
</pre>

==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]]
{{ReactOS}}
[[Категория:Переводы официальной вики]]