Описание стиля кодирования компании TouchInstinct

Именование идентификаторов

Общие правила

• Помните! Код чаще читается, чем пишется, поэтому не экономьте на понятности и чистоте кода ради скорости набора.
• Не используйте малопонятные префиксы или суффиксы.
• Не используйте подчеркивание для отделения слов внутри идентификаторов.
• Используйте стиль именования Кемел или Паскаль.

Стили именования

Паскаль – указание этого стиля оформления идентификатора обозначает, что первая буква заглавная и все последующие первые буквы слов тоже заглавные. Например, BackColor, LastModified, DateTime.

Кэмел – указание этого стиля обозначает, что первая буква строчная, а остальные первые буквы слов заглавные. Например, borderColor, accessTime, templateName.

Сокращения

• Не используйте аббревиатуры или неполные слова в идентификаторах, если только они не являются общепринятыми. Например, пишите GetWindow, а не GetWin.
• Если имеется идентификатор длиной менее трех букв, являющийся сокращением, то его записывают заглавными буквами, например System.IO, System.Web.UI.
• Имена длиннее двух букв записывайте в стиле Паскаль или Кэмел, например Guid, Xml, xmlDocument.

Пространства имен

• Используйте стиль Паскаль.
• Для пространства имен используйте имя компании, затем название продукта и, возможно, название подсистемы или существенной части проекта. Например, Touchin.Framework, Touchin.Project.Logic.
• Не используйте вложенные объявления пространств имен.

Классы и структуры

• Используйте стиль Паскаль.
• Используйте существительное (одно или несколько прилагательных и существительное) для имени класса.
• Не используйте специальных префиксов.

Интерфейсы

• Используйте стиль Паскаль.
• Используйте описывающее существительное, прилагательное или одно или несколько прилагательных и существительное для идентификатора интерфейса. Например, IComponent – это описывающее существительное, ICustomAttributeProvider – это конкретизированное прилагательными существительное, а IPersistable – это характеризующее прилагательное.
• Используйте префикс I (заглавная i) для интерфейсов.
• Старайтесь избегать интерфейсов с двумя I в начале, например IIdentifiable.
• Для пары класс-интерфейс, в которой класс является некоторой стандартной реализацией интерфейса, используйте одинаковые имена, отличающиеся только префиксом I для интерфейса. Например, IConfigurationManager и ConfigurationManager.

Перечисления

• Используйте стиль Паскаль для регистра букв в названии и значениях перечисления.
• Не используйте суффикс Enum в названии типа, вместо этого используйте более конкретный суффикс, например Style, Type, Mode, State.
• Если перечисление обладает атрибутом [Flags], используйте множественное число или суффикс Flags.
• Записывайте значения перечисления на отдельных строках.

Поля

• Непубличные поля (private, protected и protected internal) именуются в стиле Кэмел и начинаются с префикса _.
• Публичные поля именуются как Свойства
• Старайтесь не использовать публичные поля.

Методы

• Используйте стиль Паскаль (вне зависимости от области видимости метода).
• Используйте глаголы или комбинацию глагола и существительных и прилагательных для имен методов.

Свойства

• Используйте стиль Паскаль.
• В подходящих случаях используйте имя свойства, совпадающее с типом его значения.
• Старайтесь избегать использования имен свойств, совпадающих с названиями каких-либо типов, если значения этих свойств не являются значениями этих типов.

События

• Используйте стиль Паскаль.
• Для имен событий старайтесь использовать глаголы, которые описывают производимое над объектом действие.Например, Click, GotFocus или FontChanged.
• Не используйте суффиксы наподобие On, Before, After. Используйте соответствующую форму глагола, например Closing, Closed.
• При описании события также предоставляйте виртуальный protected-метод, который можно переопределить в классе-наследнике. Называйте такой метод OnXxx, где Xxx – имя события.
• Пытайтесь подобрать стандартный делегат(например, Action) и название для своих событий.

Параметры

• Используйте стиль Кэмел.
• Из имени и типа параметра должны быть понятны его назначение и смысл.

Локальные переменные

• Используйте стиль Кэмел.
• Объявляйте переменные непосредственно перед их использованием.

Стиль кода

Оформление

• Используйте табуляцию, а не пробелы для отступов.
• Избегайте строк длиннее 110 символов, переносите инструкцию на другую строку при необходимости.
• При переносе части кода инструкций и описаний на другую строку вторая и последующая строки должны быть отбиты вправо на один отступ (табуляцию).

Структура класса

Для унификации структуры классов каждый член класса должен распологаться в определенной группе. Порядок групп должен оставаться неизменным. Группы отделяются друг от друга 3 пустыми строками.

• События
• Непубличные поля, константы и инлайн свойства.
• Конструкторы
• Свойства
• Методы
• Вложенные классы

Комментарии

• Отделяйте текст комментария одним пробелом «// Текст комментария.»
• Комментируя код, старайтесь объяснять, что он делает, а не какая операция производится.

Общие советы

• Не используйте литеральные константы (магические числа, зашитые в код размеры буферов, времена ожидания и тому подобное). Лучше определите константу (если вы никогда не будете ее менять) или переменную только для чтения (если она может измениться в будущих версиях вашего класса).
• Старайтесь обрабатывать только известные вам исключения! Если целью перехвата исключений является очистка ресурсов после сбоя, лучше воспользоваться секцией finally.

Организация проектов

Именование

• Для названия проекта используйте имя продукта, затем название подсистемы. Например, ProjectName.Logic (корневой неймспейс будет Touchin.ProjectName.Logic)
• Название всех внутренних проектов должно начинатся с Touchin, чтобы их было легко отличить от проектов заказчиков. Например, Touchin.Framework

Типы

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