Стандарт кодирования
- Имена переменных составляются из слов английского языка (транслитерация русских слов не допускается).
- Имена неконстантных переменных, объектов состоят из строчных символов. Начало имени начинается со строчной буквы. Слова не разделяются символом подчеркивания «_», вместо этого каждое следующее слово начинается с заглавной буквы. Пример: isVariable.
- Имена классов, методов, структур состоят из строчных символов. Начало имени начинается с заглавной буквы. Слова не разделяются символом подчеркивания «_», вместо этого каждое следующее слово начинается с заглавной буквы. Пример: MyClass, MyMethod(). Более подробно - тут
- Длина строки равна 80 символам. Если строка программного кода не помещается целиком, она разбивается на несколько строк
- Абзацный отступ – 4 пробела.
- В строке располагается только один оператор.
- Фигурная скобка в системных выражениях располагается согласно стандартным настройкам редактора C#. Пример:
SystemWord (…)
{
// Какой-то код.
}
- Используются фигурные скобки, даже если в условном операторе имеется одна строка. Пример:
if(Something())
{
SomethigElse();
}
- Комментарии должны быть предложениями на русском языке, они должны быть хорошо составлены и иметь правильную пунктуацию, по возможности без сокращений.
- Комментарий пишется в стиле системы документирования Doxygen XML Documentation. Справка по Doxygen.
- В начале каждого заголовочного модуля (*.cs) может следовать служебная информация, содержащая сведения об авторе (основной разработчик, занимающийся поддержкой данного модуля), назначении файла, директивах препроцессора (может быть опущено при отсутствии таковых), последней версии. Формат:
/// @file modeMngr.cs
/// @brief Краткое описание.
///
/// Подробное описание.
///
/// @author Иванюк Дмитрий Сергеевич.
///
/// @par Описание директив препроцессора:
/// @c PAC - компиляция для контроллера.@n
/// @c WIN - компиляция для Windows.
///
/// @par Текущая версия:
/// @$Rev$.@n
/// @$Author$.@n
/// @$Date:: $.
- Каждое определение функции (объявление класса, структуры) может отделяться специальным комментарием (80 символов). Это подобно заголовкам разделов. Пример:
//------------------------------------------------------------------------------
- Комментирование объявления класса (структуры) может осуществляться в следующем виде:
//------------------------------------------------------------------------------
/// <summary> Removes the specified item from the collection
/// </summary>
class StepPath
{
};
- Комментирование определения функций осуществляется в следующем виде:
//------------------------------------------------------------------------------
void DescriptiveName(type descriptiveName)
{
// Здесь помещается комментарий, описывающий, как
// функция делает то, что она делает. Он может пропускаться
// если программа сама по себе достаточно содержательна.
CodeGoesHere();
}
- Каждое определение функций нового класса может отделяться специальным комментарием. Пример:
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
- Комментирование объявления методов (функций) осуществляется в следующем виде:
/// <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);
- Комментирование кода должно быть в виде блоков. Пример:
// Вот блочный комментарий, описывающий последующий блок
// программы. После общего резюме описываются некоторые
// особенности:
// 1. Этот комментарий описывает, что происходит в строке
// с меткой 1.
// 2. Этот комментарий описывает, что происходит в строке
// с меткой 2.
//
// Или используется следующий комментарий:
// Алгоритм устанавливается на начальное значение [1]. Затем
// делается...[2], после чего проверяется...[3].
//
HereIsTheCode();
while(someCondition)
{
ThisCodeIsRatherObscure(); // 1
}
MmoreStuffHere();
while(someCondition)
{
ThisCodeIsAlsoObscure(); // 2
}
- Должно использоваться форматирование кода согласно стандартных настроек редактора кода C#. Пример:
int x; // Описание что делает x.
unsigned long int (*pfi)(); // Описание что делает pfi.
int z; // Описание что делает z.
const char *theVariable; // Описание the_variable.
x = 10; // Здесь идет комментарий.
theVariable = x; // Здесь второй комментарий.
z = x; // A здесь третий.