Комментарии для документации
2017 год
Документация по исходному коду будет формироваться автоматически, поэтому:
- Документированию подлежат пространства имён и классы, включая их составляющие элементы (конструкторы, методы, свойства и проч.).
- Документация ведётся в комментариях к коду с использованием xml-разметки.
-
Строка документации должна начинаться с тройного слеша (///). Комментарий с документацией
вставляется перед описываемым элементом.
Подробно об используемых тегах можно прочитать на сайте msdn.microsoft.com.
Общие правила оформления
- Не допускается вставка комментария с текстом для документации в конец строки кода – только отдельной строкой.
- Между символами «///» и началом строки комментария ставится один пробел.
- Документация пишется на русском языке с соблюдением грамматики и пунктуации.
-
Текст комментария должен представлять собой набор предложений:
- каждое предложение начинается с заглавной буквы, в конце него ставится точка;
- между предложениями – пробелы или переход на новую строку.
- Рекомендуемая длина строк комментариев – до 80 символов.
- Если комментарий с документацией пишется в несколько строк, то открывающий и закрывающий теги лучше указывать на отдельных строках.
Требования к стилистике
- В строках документации не допускается использование сленга (не считая общепринятого в IT-сфере жаргона), ненормативной лексики, юмористической формы изложения.
- Нужно стараться описывать элементы так, чтобы это было понятно и другим людям, включая тех, кто впервые сталкивается с нашей платформой.
-
При возможности излагать мысль кратко, но не в ущерб доступности понимания.
При написании комментария в теге <summary>, нужно указывать только основную информацию, т.к. именно это описание будет отображаться во всплывающих подсказках. Дополнения и пояснения следует выносить в тег <remarks>.
При этом под краткостью понимается донесение главной информации, а не экономия символов. Если возникают сомнения в грамматической правильности написанного, то лучше использовать дополнительные слова.
Например, вместо «бизнес-объект-владелец реквизита» писать «бизнес-объект, являющийся владельцем реквизита» . -
При описании большинства элементов (исключения указаны ниже) предложение следует начинать с глагола,
используя настоящее время, третье лицо, единственное число.
Лучше использовать переходные глаголы, чтобы избежать «одушевления» описываемых объектов. Например:- вместо «Убеждается в правильности …» - «Проверяет правильность…»;
- вместо «Идёт по строкам…» - «Перебирает строки …».
Элемент Действие Класс Представляет, задает (для классов, представляющих собой атрибуты (имеют приписку Attribute в названии) Свойство Возвращает Метод Создаёт, возвращает, задаёт, преобразует, определяет и проч. Поле Представляет, указывает, определяет, содержит Оператор Сравнивает, преобразует Конструктор Инициализирует Событие Происходит -
Описание следует представлять в виде назывного предложения (подлежащее без сказуемого),
когда документируются:
- интерфейсы;
- параметры;
- возвращаемые значения.
-
При описании исключения указывается предложение, близкое к текстовой формулировке исключения.
Например, «Недопустимое значение идентификатора объекта.», «Не найден указанный объект».
То есть это должен быть текст, похожий на тот, который мог бы выводиться в сообщение при возникновении исключения. - Нужно стараться не использовать сокращения и аббревиатуры (кроме общепринятых и однозначно трактуемых).
- Не заменять букву «ё» на «е».
- Если свойство/метод наследуется от родительского класса, то дополнительно его описывать не нужно (информация в документацию попадёт). Если метод родительского класса переопределяется, то нужно его описать (в документацию попадёт описание и пометка о том, какой метод переопределён).
-
В случаях, когда есть сомнения в формулировке описания, рекомендуется равняться на документацию
к схожим элементам на сайте msdn.microsoft.com
(в частности для переопределённых стандартных методов).
При этом стоит учитывать тот факт, что описания на этом сайте являются переведёнными с другого языка и иногда требуют корректировки.
Специфика
-
Для описания некоторых элементов достаточно использовать теги <summary> и <remarks>
(например, для свойств и полей класса). Для других элементов требуется использовать и специальные теги.
Например, при описании метода нужно вставлять отдельные теги для параметров, возвращаемых значений, исключений. - При упоминании других элементов следует делать ссылку на них для возможности перейти на страницу описания этих элементов.
-
Принято правило не делать ссылку на класс при описании конструктора, наименование которого совпадает
с инаименованием класса.
Если конструктор один, то достаточно описать его строкой «Инициализирует новый экземпляр класса.». -
При использовании ссылки на элемент следует перед его названием указать его принадлежность (класс, свойство и проч.)
Например: вместо «Не применен <see cref="BasisPropertyAttribute"/gt;.» писать «Не применен атрибут <see cref="BasisPropertyAttribute"/gt;.». - Если используются названия системных классов, методов и проч. (в том числе названия типов данных), то также следует оформлять их в виде ссылки, причём ссылки на внешний ресурс – сайт Microsoft с описанием элемента.
-
Если описываемый элемент имел аналог в старом проекте (С++), то в конце описания
следует указать его прежнее наименование отдельной строкой в виде:
/// <![CDATA[ПрежнееНазвание]]>
- Если описываемый класс является статическим или абстрактным, то следует это указать.
- В случае изменения комментария к виртуальному методу базового класса или переопределенному методу наследуемого класса необходимо отследить всю цепочку наследования и при необходимости сделать аналогичные правки.
- Решено не использовать тег <code>, вместо него указывать <c>.
- В тег <c> оформлять даже части кода, состоящие и одного слова (например, «true», «false», «null»).
-
Иноязычные слова (включая названия элементов) считать несклоняемыми.
Т.е. не следует писать, например, так: «AssemblyConfigurator'ом» - Вместо слова «Имя» лучше использовать «Наименование» или «Название».
Словарь часто встречающихся формулировок.
Исключения:
Наименование | Формулировка |
ArgumentNullException | Пустое значение параметра функции. |
ArgumentException | Недопустимое значение параметра функции. |
Часто встречающиеся орфографические, пунктуационные и грамматические ошибки, нарушения принятого стиля описания.
Неправильно | Правильно | Комментарий |
Признак что объект хранится в БД. | Признак того, что объект хранится в базе данных. |
|
Инициализирует новый экземпляр класса, с указанным сообщением об ошибке. | Инициализирует новый экземпляр класса с указанным сообщением об ошибке. | Если не получается объяснить постановку запятой, то надёжнее её не ставить. |
Задает информацию о выходном параметре узла (элемента) бизнес-процесса, с учетом его результата выполнения. | Задаёт информацию о выходном параметре узла (элемента) бизнес-процесса с учётом результата его выполнения. |
|
Строковое представление наименования параметра. | Наименование параметра. | Это описание возвращаемого значения типа String. Тип в документацию попадает, поэтому не требуется указывать на него в описании. |
Возвращает тип бизнес-объекта реквизита ссылки по локализованному наименованию. | Возвращает тип бизнес-объекта, на который ссылается реквизит. |
|