Разработчику > Комментарии для документации

Комментарии для документации

Документация по исходному коду будет формироваться автоматически, поэтому:

  1. Документированию подлежат пространства имён и классы, включая их составляющие элементы (конструкторы, методы, свойства и проч.).
  2. Документация ведётся в комментариях к коду с использованием xml-разметки.
  3. Строка документации должна начинаться с тройного слеша (///). Комментарий с документацией вставляется перед описываемым элементом.
    Подробно об используемых тегах можно прочитать на сайте msdn.microsoft.com.

Общие правила оформления

  1. Не допускается вставка комментария с текстом для документации в конец строки кода – только отдельной строкой.
  2. Между символами «///» и началом строки комментария ставится один пробел.
  3. Документация пишется на русском языке с соблюдением грамматики и пунктуации.
  4. Текст комментария должен представлять собой набор предложений:
    • каждое предложение начинается с заглавной буквы, в конце него ставится точка;
    • между предложениями – пробелы или переход на новую строку.
  5. Рекомендуемая длина строк комментариев – до 80 символов.
  6. Если комментарий с документацией пишется в несколько строк, то открывающий и закрывающий теги лучше указывать на отдельных строках.

Требования к стилистике

  1. В строках документации не допускается использование сленга (не считая общепринятого в IT-сфере жаргона), ненормативной лексики, юмористической формы изложения.
  2. Нужно стараться описывать элементы так, чтобы это было понятно и другим людям, включая тех, кто впервые сталкивается с нашей платформой.
  3. При возможности излагать мысль кратко, но не в ущерб доступности понимания.
    При написании комментария в теге <summary>, нужно указывать только основную информацию, т.к. именно это описание будет отображаться во всплывающих подсказках. Дополнения и пояснения следует выносить в тег <remarks>.
    При этом под краткостью понимается донесение главной информации, а не экономия символов. Если возникают сомнения в грамматической правильности написанного, то лучше использовать дополнительные слова.
    Например, вместо «бизнес-объект-владелец реквизита» писать «бизнес-объект, являющийся владельцем реквизита» .
  4. При описании большинства элементов (исключения указаны ниже) предложение следует начинать с глагола, используя настоящее время, третье лицо, единственное число.
    Лучше использовать переходные глаголы, чтобы избежать «одушевления» описываемых объектов. Например:
    • вместо «Убеждается в правильности …» - «Проверяет правильность…»;
    • вместо «Идёт по строкам…» - «Перебирает строки …».
    В большинстве случаев подходят следующие глаголы:
    Элемент Действие
    Класс Представляет, задает (для классов, представляющих собой атрибуты (имеют приписку Attribute в названии)
    Свойство Возвращает
    Метод Создаёт, возвращает, задаёт, преобразует, определяет и проч.
    Поле Представляет, указывает, определяет, содержит
    Оператор Сравнивает, преобразует
    Конструктор Инициализирует
    Событие Происходит
  5. Описание следует представлять в виде назывного предложения (подлежащее без сказуемого), когда документируются:
    • интерфейсы;
    • параметры;
    • возвращаемые значения.
    Например, «Наименование реквизита.», «Значение в указанном формате.».
  6. При описании исключения указывается предложение, близкое к текстовой формулировке исключения.
    Например, «Недопустимое значение идентификатора объекта.», «Не найден указанный объект».
    То есть это должен быть текст, похожий на тот, который мог бы выводиться в сообщение при возникновении исключения.
  7. Нужно стараться не использовать сокращения и аббревиатуры (кроме общепринятых и однозначно трактуемых).
  8. Не заменять букву «ё» на «е».
  9. Если свойство/метод наследуется от родительского класса, то дополнительно его описывать не нужно (информация в документацию попадёт). Если метод родительского класса переопределяется, то нужно его описать (в документацию попадёт описание и пометка о том, какой метод переопределён).
  10. В случаях, когда есть сомнения в формулировке описания, рекомендуется равняться на документацию к схожим элементам на сайте msdn.microsoft.com (в частности для переопределённых стандартных методов).
    При этом стоит учитывать тот факт, что описания на этом сайте являются переведёнными с другого языка и иногда требуют корректировки.

Специфика

  1. Для описания некоторых элементов достаточно использовать теги <summary> и <remarks> (например, для свойств и полей класса). Для других элементов требуется использовать и специальные теги.
    Например, при описании метода нужно вставлять отдельные теги для параметров, возвращаемых значений, исключений.
  2. При упоминании других элементов следует делать ссылку на них для возможности перейти на страницу описания этих элементов.
  3. Принято правило не делать ссылку на класс при описании конструктора, наименование которого совпадает с инаименованием класса.
    Если конструктор один, то достаточно описать его строкой «Инициализирует новый экземпляр класса.».
  4. При использовании ссылки на элемент следует перед его названием указать его принадлежность (класс, свойство и проч.)
    Например: вместо «Не применен <see cref="BasisPropertyAttribute"/gt;.» писать «Не применен атрибут <see cref="BasisPropertyAttribute"/gt;.».
  5. Если используются названия системных классов, методов и проч. (в том числе названия типов данных), то также следует оформлять их в виде ссылки, причём ссылки на внешний ресурс – сайт Microsoft с описанием элемента.
  6. Если описываемый элемент имел аналог в старом проекте (С++), то в конце описания следует указать его прежнее наименование отдельной строкой в виде:
    /// <![CDATA[ПрежнееНазвание]]>
                                    
  7. Если описываемый класс является статическим или абстрактным, то следует это указать.
  8. В случае изменения комментария к виртуальному методу базового класса или переопределенному методу наследуемого класса необходимо отследить всю цепочку наследования и при необходимости сделать аналогичные правки.
  9. Решено не использовать тег <code>, вместо него указывать <c>.
  10. В тег <c> оформлять даже части кода, состоящие и одного слова (например, «true», «false», «null»).
  11. Иноязычные слова (включая названия элементов) считать несклоняемыми.
    Т.е. не следует писать, например, так: «AssemblyConfigurator'ом»
  12. Вместо слова «Имя» лучше использовать «Наименование» или «Название».

Словарь часто встречающихся формулировок.

Исключения:
Наименование Формулировка
ArgumentNullException Пустое значение параметра функции.
ArgumentException Недопустимое значение параметра функции.
Часто встречающиеся орфографические, пунктуационные и грамматические ошибки, нарушения принятого стиля описания.
Неправильно Правильно Комментарий
Признак что объект хранится в БД. Признак того, что объект хранится в базе данных.
  1. Это сложное предложение: нужна запятая.
  2. Сокращение БД лучше не использовать.
Инициализирует новый экземпляр класса, с указанным сообщением об ошибке. Инициализирует новый экземпляр класса с указанным сообщением об ошибке. Если не получается объяснить постановку запятой, то надёжнее её не ставить.
Задает информацию о выходном параметре узла (элемента) бизнес-процесса, с учетом его результата выполнения. Задаёт информацию о выходном параметре узла (элемента) бизнес-процесса с учётом результата его выполнения.
  1. Не каждой паузе в речи соответствует запятая на письме.
  2. Не следует игнорировать букву «ё».
Строковое представление наименования параметра. Наименование параметра. Это описание возвращаемого значения типа String. Тип в документацию попадает, поэтому не требуется указывать на него в описании.
Возвращает тип бизнес-объекта реквизита ссылки по локализованному наименованию. Возвращает тип бизнес-объекта, на который ссылается реквизит.
  1. Хорошо бы перечитывать написанный комментарий через некоторое время и анализировать, то ли получилось, что имелось в виду.
    В данном случае получилось, будто у ссылки есть некий реквизит, у которого есть бизнес-объект, тип которого и возвращает метод. Если «ссылки» ‒ это приложение к «реквизита», (т.е. реквизит сам является ссылкой, а не принадлежит ей), то нужен дефис.)
  2. Входные параметры не обязательно указывать при описании метода.