Какую информацию предоставить в комментариях Xml?

Question

Когда я пишу метод и хочу его комментировать, я записываю ту же информацию в тег итога.

Пример:

/// <summary>
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary>
/// <param name="id">customer id</param>
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns>
private Customer GetCustomerById(string id)
{
   ...
}

Наконец, это действительно полезно?Какую информацию предоставляют и в каком теге их предоставлять?

Answer 1

Рассмотрите СУХОЙ (не повторяйтесь).Запись param описывает параметр, а запись возврата описывает, что возвращается.Сводка должна содержать обзор того, что делает метод, а не повторять информацию из этих других записей.

Отсутствует ваша документация - это фактическая документация.«Идентификатор строки» - это строка, в которой есть идентификатор - самодокументируемый.Но как мне вызвать этот метод: что включает в себя действительный идентификатор пользователя?Что произойдет, если я передам нулевую или пустую строку?и т. д.

Вот гипотетический пример, который включает документацию о том, для чего и как использовать метод:

/// <summary> Gets information on a customer </summary>
///
/// <param name='id'> A customer identifier in the form of a GUID string.
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}".
/// Braces around the GUID are optional.
/// This parameter must be a valid Guid. </param>
///
/// <returns> A Customer record describing the given customer, or
/// null if the Customer is not found</returns>

Если вы используете инструмент, подобный моему надстройке ( Atomineer ProДокументирование ) затем репликация такого рода параметров параметров вокруг класса является тривиальной задачей, поэтому не требуется много времени для правильного документирования ваших методов.

Answer 2

Ответ на другой вопрос также ответит на ваш:

Действительно ли предоставление документации действительно полезно?

Предоставьте все, что вы хотите, что вы считаете необходимым и полезным. Эта информация будет отображаться для потребителя кода в Visual Studio в виде всплывающей подсказки IntelliSense, как вы видите для классов и членов .NET.

Answer 3

XML документация очень полезна, если вы разрабатываете библиотеку.Файл справки может быть автоматически создан на основе этих комментариев xml.См. this для подробного обсуждения создания файла справки.Для получения информации о теге документации XML, проверьте MSDN .

Answer 4

Во многих случаях я считаю, что лучше всего полностью исключить возвращаемый элемент. Похоже, ваш пример является отличным примером этого. К счастью, VStudio не помечает это как плохой комментарий с предупреждением. Причина, по которой я это делаю, заключается в том, что в 80% случаев моя документация в основном описывает, что тип возвращаемого значения уже есть, или название функции настолько очевидно, что это бесполезная трата времени и энергии моя оценка, чтобы включить это, и это часто приводит к нарушению СУХОЙ.

Ваш пример - прекрасный пример этого.

Customer GetCustomerById(string id)

Если бы это был int id, эта функция может даже не нуждаться в комментариях. Со строкой это менее понятно и может использовать некоторые пояснения. Но в любом случае представляется бесполезной попытка предоставить XML-комментарий к типу возвращаемого значения. Имейте в виду, что это субъективный вопрос, некоторые люди могут предпочесть для завершения всегда включать комментарий типа возврата, это нормально. Я рад, что это не требуется, начиная с системы предупреждений VStudio.

Answer 5

Иногда имена методов или свойств говорят сами за себя, но это не всегда так.Событие с вашим примером.Вы должны предоставить информацию о том, что произойдет, если предоставленный ID не существует.Будет ли ваш метод генерировать исключение (если так, то какое это будет исключение) или, может быть, просто вернуть ноль, или какое-то общее значение Customer.Empty?Иногда вы могли бы даже предоставить пример кода.

В любом случае, всегда полезно предоставить документацию по коду в любом случае.