codestyle.md

Содержание

Стандарт кодирования

• Общие требования
  • Именование переменных
  • Форматирование текста программы
  • Написание комментария

Стандарт кодирования

1 Общие требования

1.1 Именование переменных

1. Имена переменных составляются из слов английского языка (транслитерация русских слов не допускается).
2. Имена неконстантных переменных, объектов состоят из строчных символов. Начало имени начинается со строчной буквы. Слова не разделяются символом подчеркивания «_», вместо этого каждое следующее слово начинается с заглавной буквы. Пример: isVariable.
3. Имена классов, методов, структур состоят из строчных символов. Начало имени начинается с заглавной буквы. Слова не разделяются символом подчеркивания «_», вместо этого каждое следующее слово начинается с заглавной буквы. Пример: MyClass, MyMethod(). Более подробно - тут

1.2 Форматирование текста программы

1. Длина строки равна 80 символам. Если строка программного кода не помещается целиком, она разбивается на несколько строк
2. Абзацный отступ – 4 пробела.
3. В строке располагается только один оператор.
4. Фигурная скобка в системных выражениях располагается согласно стандартным настройкам редактора C#. Пример:

SystemWord (…)
{
    // Какой-то код.
}

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

if(Something())
{
    SomethigElse();
}

1.3 Написание комментария

1. Комментарии должны быть предложениями на русском языке, они должны быть хорошо составлены и иметь правильную пунктуацию, по возможности без сокращений.
2. Комментарий пишется в стиле системы документирования Doxygen XML Documentation. Справка по Doxygen.
3. В начале каждого заголовочного модуля (*.cs) может следовать служебная информация, содержащая сведения об авторе (основной разработчик, занимающийся поддержкой данного модуля), назначении файла, директивах препроцессора (может быть опущено при отсутствии таковых), последней версии. Формат:

/// @file modeMngr.cs
/// @brief Краткое описание.
///
/// Подробное описание.
///
/// @author Иванюк Дмитрий Сергеевич.
///
/// @par Описание директив препроцессора:
/// @c PAC - компиляция для контроллера.@n
/// @c WIN - компиляция для Windows.
///
/// @par Текущая версия:
/// @$Rev$.@n
/// @$Author$.@n
/// @$Date:: $.

4. Каждое определение функции (объявление класса, структуры) может отделяться специальным комментарием (80 символов). Это подобно заголовкам разделов. Пример:

//------------------------------------------------------------------------------

5. Комментирование объявления класса (структуры) может осуществляться в следующем виде:

//------------------------------------------------------------------------------
/// <summary> Removes the specified item from the collection
/// </summary>
class StepPath
{
};

6. Комментирование определения функций осуществляется в следующем виде:

//------------------------------------------------------------------------------
void DescriptiveName(type descriptiveName)
{
    // Здесь помещается комментарий, описывающий, как
    // функция делает то, что она делает. Он может пропускаться
    // если программа сама по себе достаточно содержательна.
    CodeGoesHere();
}

7. Каждое определение функций нового класса может отделяться специальным комментарием. Пример:

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

8. Комментирование объявления методов (функций) осуществляется в следующем виде:

/// <summary> Removes the specified item from the collection
/// </summary>
/// <param name="newCloseDevCnt">The item to remove
/// </param>
/// <param name="newOpenDevCnt">The group containing the item
/// </param>
/// <remarks>
/// If parameter "NewOpenDevCnt" is null, an exception is raised.
/// <see cref="EArgumentNilException"/>
/// </remarks>
/// <returns>True if the specified item is successfully removed;
/// otherwise False is returned.
/// </returns>
int SetDevCnt(uint2 newCloseDevCnt,
    uint2 newOpenDevCnt);

9. Комментирование кода должно быть в виде блоков. Пример:

// Вот блочный комментарий, описывающий последующий блок
// программы. После общего резюме описываются некоторые
// особенности:
// 1. Этот комментарий описывает, что происходит в строке
// с меткой 1.
// 2. Этот комментарий описывает, что происходит в строке
// с меткой 2.
//
// Или используется следующий комментарий:
// Алгоритм устанавливается на начальное значение [1]. Затем
// делается...[2], после чего проверяется...[3].
//

HereIsTheCode();
while(someCondition)
{
    ThisCodeIsRatherObscure();  // 1
}
MmoreStuffHere();
while(someCondition)
{
    ThisCodeIsAlsoObscure();    // 2
}

10. Должно использоваться форматирование кода согласно стандартных настроек редактора кода C#. Пример:

int x;  // Описание что делает x.
unsigned long int (*pfi)(); // Описание что делает pfi.
int z;  // Описание что делает z.
const char *theVariable;    // Описание the_variable.
x = 10; // Здесь идет комментарий.
theVariable = x;    // Здесь второй комментарий.
z = x;  // A здесь третий.