Сообщение от xprogramming.com.ua
1. О руководстве "Стиль кодирования на С#" в рамках Gray LLC
Данный документ написан на основе неофициального стандарта предложенного Mike Krueger. (The SharpDevelop C# Coding Style Guide by Mike Krueger). Благодаря данному документу у Вас есть возможность разрабатывать "читабельный" код и как следствие надежный и легко переносимый. Основным в нем является правила форматирования кода, написанного на языке C#, но большинство приемов можно применить и для других языков программирования.
Документ разрабатывался для компании Gray LLC.
2. Организация файлов
2.1 Исходные файлы на C#
Старайтесь сохранять структуру классов/файлов небольшими размерами, до 2000 строк кода. Разделяйте код на файлы, это поможет Вам создавать более четкую инфраструктуру приложения. Помещайте каждый класс в отдельный файл с одноименным названием (совпадающее с названием класса) и расширением .cs.
2.2 Дерево файловых директорий
Создавайте директорию для каждого namespace.
Например для: MyProject.TestSuite.TestTier иерархия директорий будет иметь следующий вид: MyProject / TestSuite / TestTier.
Как видно из пример точка в строке namespace заменяется на символ слеша ("/") при написании директорий.
3. Структурированное расположение текста
3.1 Длина строки
Старайтесь избегать (насколько это возможно) строк, длинной более 80–ти символов. Присутсвие линейки в редакторе кода значительно облегчает этот контроль. Если строка превышает размер 80-ти символов используйте синтаксис переноса строки (см. 3.2)
3.2 Перенос длинных строк
В том случае, если строка превышает длину 80 символов, то для ее переноса используются основные принципы описанные ниже.
Строку можно переносить в случае, если:
Перенос после запятой.
Перенос после оператора.
Перенесенная линия по отношению к верхней должна быть сдвинута вправо как минимум на один стандартный символ табуляции либо на уровне начала переносимого выражения (см. примеры).
Символ Табуляции в редакторе устанавливается размером, равным 4-м стандартным символам.
Пример разбиения строки при вызове аргументов метода:
longMethodCall(expr1, expr2, expr3,
expr4, expr5);
Пример переноса арифметического выражения несколькими способами. Первый стандартным образом (с одинарным символом табуляции).
var = a * b / (c - g + f) +
4 * z; // PREFER
и вторым (с форматированием по переносимому выражению)
var = a * b / (c - g +
f) + 4 * z; // AVOID
3.3 Пробелы
Никто, кто хочет достичь качественного уровня написания кода не должен использовать пробелы для форматирования отступов в коде. И делается это потому, что разные разработчики используют различное число для символов табуляции. Один – размер 2-х символов, другой 4-ре третий 8-мь. В случае, если вы будете использовать стандартный табулятор для отступа, то любой разработчик может перенастроить его под свой стандарт, что значительно облегчит модификацию написанного кода в будущем.
Вот несколько аргументов в пользу использования табулятора:
Каждый может настроить отступ под свой стандар;
Использование одного символа вместо 2-х, 4-х или 8-ми. И что самое важное легкость в выравнивании отступов: сделать это одним нажатием гораздо легче, чем несколькими;
Если Вы захотите передвинуть выделенный текст на одну табуляцию вправо (клавиша Tab) или влево (Shift+Tab) то сделать это не составит труда. Большинство редакторов имеют эту возможность.
Этих аргументов должно быть достаточно для того, что бы ни использовать пробелы при форматировании исходного кода.
!!! НЕ ИСПОЛЬЗУЙТЕ ПРОБЕЛЫ ВМЕСТО СИМВОЛОВ ТАБУЛЯЦИИ !!!!
4. Comments
4.1 Блочный комментарий
Как правило, используется блочный комментарий для описания, а так же стандартный «///» комментарий для самодокументирования.
Для стандартных блочных комментариев используются следующие стили:
/*
* Line 1
* Line 2
* Line 3
*/
либо такой стиль:
/* blabla */
4.2 Комментарий "до конца строки"
Для комментариев в одну строку используется «С++» подобный стиль: «//» Этот стиль наиболее удобен при документировании параметров. Предпочтительно использовать данный стиль вместо /* комментарий */ там, где это возможно.
int i; // переменная для цикла
4.3 Комментарии для самодокументирования
Теги для самодокументирования, также могут использоваться разработчиками для описания. Но должен учитываться и тот факт, что он должен согласовываться с требованиями к документированию исходного кода.<c> <para> <see>
<code> <param> <seealso>
<example> <paramref> <summary>
<exception> <permission> <value>
<include> <remarks>
<list> <returns>
Данный раздел подробно описан в документации Microsoft
|