Как избежать избыточности в комментариях к документации?

Мы только начали использовать StyleCop, и с этим мне трудно справляться, это требования к документации. Я не хочу обсуждать полезность инструмента, мне просто интересно, есть ли у кого-нибудь какие-либо рекомендации или способы мышления о документировании методов, которые делают комментарии полезными. Я считаю, что мои комментарии часто содержат много повторений, чтобы удовлетворить требованиям StyleCop, например:

    /// <summary>
    /// Gets a dto of personal info.
    /// </summary>
    /// <param name="userId">
    /// The id of the user.
    /// </param>
    /// <returns>
    /// A dto containing personal info.
    /// </returns>
    public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

Существует ли стандартный способ выражения сводной информации о возврате? Что вы помещаете в описания параметров?

Ответ 1

Я стараюсь избегать дубликатов, описывая процесс также в сводке. В параметрах вы можете добавлять такие данные, как допустимые диапазоны, или как пользователь должен получить эту информацию. Для возвратов я также перечисляю любые условия ошибки, например:

/// <summary>
/// Gets a dto of personal info by querying the current list of users (or active directory or SQL)
/// </summary>
/// <param name="userId">
/// The id of the user. Must be greater than 0. The ID is stored in the application context or can be retrieved by a call to GetUserIdByName.
/// </param>
/// <returns>
/// A dto containing personal info. Returns null if the specified user information was not found.
/// </returns>
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

Ответ 2

Если на вас навязывается, тогда вам просто придется страдать с некоторым повторением, поскольку вы уже используете хорошие самодокументирующие методы, такие как интеллектуальное именование.

Другие хорошие вещи, которые вы могли бы включить в документацию, были бы следующими: 1) Форматирование. Существуют ли ограничения на идентификатор пользователя, например "Все пользователи ниже 500 являются администраторами" или что-то в этом роде? Они хороши для комментариев с параметром.

2) Исключения. Если ваш метод собирается бросить или передать один, запишите его, чтобы люди, использующие его, знали, как справиться с ним.

3) Образцы кода - показ того, как использовать ваш метод

4) Особые условия - будет ли возвращаемый объект в каком-либо нечетном состоянии? Если идентификатор пользователя не найден, вы возвращаете нулевую или пустую/ошибку PersonalInfoDTO?

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

Ответ 3

Существует причина для применения этого стандарта, даже если вы считаете, что это иногда избыточная информация. (т.е. "userId → идентификатор пользователя" ). Этот комментарий также неявно содержит информацию о том, что для этого параметра нет дополнительных ограничений.

Итак,

...
///<param name="angle"> 
///The angle in degrees. Must be below 360 and above 0.
///</param>
...

Если вы не добавляете, что "должно быть ниже x и выше y", то вы заявляете, что нет ограничений на параметр.

Аналогично для < возвращает > тег. Вы можете подумать, что возвращаемое значение самоочевидно, но <return> , где вы должны сообщать вызывающей стороне, может ли это вернуть null при ошибке. Или если он возвращает одно значение, даже если есть список возможных ответов.

Этот вид информации очень важен, и стилькод просто принуждает вас добавить его.

Ответ 4

Jayrdub:

Имейте в виду, что суть этих комментариев заключается в создании документации для вашего кода. Резервирование в порядке, так как различные части этих комментариев могут использоваться по-разному в разных сценариях - не все ваши комментарии могут использоваться в определенных обстоятельствах.

Хотя XML-документ полезен для создания файлов справки в стиле MSDN, он также широко используется в intellisense и всплывающих подсказках в Visual Studio. Ваше резюме будет видно в определенное время, ваши теги param будут видны в другое время, и ваш тег возврата будет отображаться еще в другое время. Иногда они все будут видны вместе, а иногда и нет.

Короче говоря, избыточность полезна. Он предоставляет вам помощь в качестве программиста в разных обстоятельствах, когда вы используете метод или класс, который он документирует.

Ответ 5

", что делает комментарии действительно полезными. Я считаю, что мои комментарии часто содержат много повторений, чтобы удовлетворить требованиям StyleCop"

Полезные и избыточные не имеют ничего общего друг с другом.

Вы не определили "полезный" в своем вопросе. Обычно это означает "больше, чем требуется по стилю". Если вы чувствуете потребность написать что-то еще, то напишите еще что-нибудь. Stylecop является минимальным; вы можете пройти выше и ниже этих минимумов.

В вашем случае, поскольку вы пишете резюме функции, которая очень мало. Очень распространено, что формальные элементы (параметры и типы возвращаемых данных) и резюме будут повторяться. Я не уверен, как это повторение не дает "полезного" теста. Возможно, если там что-то не хватает, вы можете добавить его. Не стесняйтесь расширять и писать больше - ничто не мешает вам писать "полезную" документацию, которая больше, чем минимум.

Резервный - в то время как утомительный - кажется, не может быть полезным.

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

Для более сложных классов (и функций) сводка - это место для расширения на нюанс. Например, "почему?" или "когда он может и не может быть использован", и "другие ограничения" и "образцы кода" и такие вещи, которые были бы более полезными.

В любое время вы можете - и должны - писать больше, чем минимум. Однако для тривиальных функций нет смысла писать больше, чем минимум.

Ответ 6

Я, как правило, очень подозрительно отношусь к инструментам, которые заставляют вас добавлять комментарии в очень произвольных местах.

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

Если комментарии могут быть сгенерированы автоматическим инструментом... тогда у людей нет бизнеса, пишущих их в первую очередь. Если это необходимо по какой-либо другой причине (например, для создания внешней документации), вы должны иметь некоторую форму автоматизированного script для их создания и поместить результаты в ненавязчивое местоположение.

Конечно, есть много значимых вещей, которые вы могли бы сказать об этом функциональном интерфейсе. Каковы границы параметров, например.

Ответ 7

Существует много повторений - худшее ИМХО - это Свойства, где вы должны заполнить значение <value> , описывающее свойство, но intellisense показывает только < summary, которое для свойства может только реально описывать То же самое, поэтому вы в конечном итоге говорите то же самое дважды.

Я попытаюсь кратко суммировать свойство/метод в сводке, но поместить более подробные описания в поля <param> , <value> и <returns> , чтобы они предоставили некоторую действительно более полезную информацию. (например, могут ли они передаваться как null и т.д.)

Вторая вещь, которую я делаю, это использование надстройки, которую я написал для автоматического создания и автоматического обновления) комментариев Doc, чтобы я минимизировал работу, связанную с документированием кода, - если автоматизированный инструмент может заполнить большая часть деталей для меня, это сводит к минимуму усилия, связанные с поддержанием этой "дублированной" информации. Он также автоматически форматирует и переносит слова, чтобы сохранить их в порядке.

Для получения дополнительной информации и бесплатной загрузки см. http://www.atomineer.com/AtomineerUtils.html.

Ответ 8

Вы можете сделать это полезным:

/// <summary>
/// Gets the user personal information.
/// </summary>
/// <remarks>
/// We need this data transfer object in order to bridge Backend.SubsystemA
/// and Backend.SubsystemB. The standard <see cref="PersonalInfo"/> won't
/// work.
/// </remarks>
/// <param name="userId">Integer representing the user ID.</param>
/// <returns>
/// <see cref="PersonalInfoDTO"/> representing the user, or <c>null</c>
/// if not available.
/// </returns>
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

Для меня summary - это информация высокого уровня, "что является целью этого метода", remarks для дальнейшего объяснения, а see - это то, где вы можете легко перемещать свою документацию. Каждый из них добавляет ценность.

Я действительно люблю комментарии к документации благодаря ReSharper. Я переназначил команду QuickDoc на CTRL+SHIFT+Q.

Ответ 9

Если вы занимаетесь Java, вы должны быть осторожны с полной документацией - чем больше вы документируете, тем меньше шансов, что пользователи найдут то, что действительно актуально. Добавление дополнительной разметки только ухудшает ее.

Возможно, вам захочется рассмотреть только захват "директив" или, по крайней мере, очень ярко их выделить.

Смотрите мой подробный ответ на "советы по написанию большого javadoc" , которые основаны на моем Ph.D. исследования по этой теме.

Ответ 10

Проблемы следующие:

Правильно. Никто не мешает вам писать комментарий, но им становится все труднее поддерживать. Кто-то, читающий код, может запутаться, если комментарий не соответствует коду. Допустим, мы все изменим код позже и забудем/не успеем их обновить. Мент
Некоторые методы очень просты и не нуждаются в комментариях.
Сложнее читать через 1000 строк, чем 100 строк правильно написанного кода. Да даже с визуальной окраской студии
Требуется много времени, чтобы прокомментировать КАЖДЫЙ ОДИНОЧНЫЙ МЕТОД в вашем коде.
Эти комментарии одобрены, если вы создаете библиотеку, но не для чего-то не используемого повторно... например, для небольшого приложения silverlight.