Что такое наилучшая практика для документирования кода C# с комментариями XML?

Я просматриваю новый код, который я только что написал, и добавляю комментарии NDoc sytle к моим классам и методам. Я надеюсь создать хороший документ MSDN для справки.Что такое наилучшая практика для документирования кода C# с комментариями XML?

В целом, какие хорошие рекомендации при написании комментариев для класса и метода? Что должны делать комментарии NDoc? Что они не должны сказать?

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

источник

2010-06-29 Esteban Araya

В комментариях используются для создания документации по API, вам необходимо:

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

источник

2010-06-29 17:58:55

+1. Мне очень нравится подсказка. –

+1. Я думаю, что основной упор на документацию должен быть на публичные интерфейсы, даже больше при создании внешних документов (doxygen, NDoc и т. Д.). Клиентам не нужно знать каждый уголок и заголовок вашего класса. Детали реализации не нужно документировать в этом формате; основное внимание должно быть уделено публичному интерфейсу, способу его использования, условиям до/после сообщения и другим вещам, которые указал Джефф. – stinky472

Разумеется, должна быть последовательная и эффективная документация для публичного интерфейса, но если ваша работа включает в себя обновление, изменение или переписывание существующей базы кода, очень важна документация о частных и защищенных объектах. – EoRaptor013

Если вы закончите с комментариями, которые не добавляют никакой ценности, они просто расточительны.

Например

/// <summary> 
/// Gets manager approval for an action 
/// </summary> 
/// <param name="action">An action object to get approval for</param> 
public void GetManagerApprovalFor(Action action)

... Вы не добавили абсолютно никакого значения и только что добавили больше кода для поддержания.

Слишком часто код завален этими лишними комментариями.

источник

2010-06-29 17:51:08 CaffGeek

Да, я понимаю, что комментарии не могут дать никакой ценности. Вот почему я ищу рекомендации по комментариям, которые обеспечивают ценность. –

Я думаю, что это скорее пример плохой документации, а не пример того, где ее не следует использовать. Публичные методы должны иметь дополнительную документацию, такую как ожидаемые исключения, предпосылки и т. Д. Например, что делает этот метод, когда действие равно null? –

Несмотря на то, что я согласен с вами в отношении суеверных комментариев, сверхдоходная документация - это другое дело. В некоторых случаях может быть, что у вас просто нет ничего лишнего для документирования, а ваша строка xml doc - это просто эхо имени метода, однако я все же добавляю, что docsctring - отчасти потому, что он подтверждает, что метод такой же простой, как кажется (скорее чем кто-то, не докучающий метод), но в основном потому, что он просто выглядит ** неправильным **, если его нет. – Justin

Для свойств ваш комментарий должен указывать, является ли свойство только для чтения, только для записи или чтения записи. Если вы посмотрите на всю официальную документацию по MS, комментарии к документам свойств всегда начинаются с «Gets ...», «Gets or sets ...» и (очень редко избегайте обычно только свойств записи) «Sets ...»

источник

2010-06-29 17:51:48

Отлично! Любые идеи для методов и классов? –

Честно говоря, единственная компания, которая серьезно относится к комментариям к Doc, - это Microsoft :) Я бы просто просмотрел их комментарии и почувствовал, как они это делают. У них определенно есть стандарты относительно того, как следует отформатировать комментарии и что они должны сказать. MS также хорошо показывает, какие исключения вызывает метод. К сожалению, комментарии doc в конечном итоге используются в качестве групповой помощи для устранения незначительных проблем на языке C# языка IMO (например, полагаясь на комментарий или ошибку компилятора, чтобы узнать, только ли свойство читается, это раздражает меня) –

Я серьезно отношусь к комментариям к документу и я не работаю для Microsoft. Между хорошими комментариями к документации, GhostDoc и Sandcastle/Sandcastle Help File Builder, наши основные библиотеки могут предложить разработчикам веб-сайтов для справки. Мне очень не нравится, когда нужно использовать методы/свойства, перейдя через код, а не читая сжатый документ. –

Как указано на MSDN page, вы используете комментарии документации XML для автоматической генерации документации, поэтому разработчики чувствуют, что если вы пишете API и не хотите работать дважды как с кодом, так и с документацией, с дополнительным преимуществом сохранения их в sync - каждый раз, когда вы меняете код, вы изменяете соответствующие комментарии и регенерируете документы.

Компиляция с помощью /doc, и компилятор будет искать все теги XML в исходном коде и создать файл документации XML, а затем использовать такой инструмент, как Sandcastle, для создания полных документов.

источник

2010-06-29 17:57:39 luvieere

Я раскрыл преимущества и возможности документации XML. Мне нужно немного помочь в том, что люди действительно находят полезным в этих комментариях. –

@Esteban Araya, как я уже сказал, близость к фактическому документу, который вы документируете, позволяя вам документировать изменения на месте, без необходимости переключения на другое приложение и поиска подходящего места для изменения. – luvieere

Одна вещь о комментариях ОБНОВЛЯЕТ их. Слишком много людей изменяют функцию, а затем не меняют комментарий, чтобы отразить изменение.

источник

2010-06-29 17:58:46 Brian

Правда. Мы исправили это в прошлом, сделав его частью стандартного контрольного списка проверки кода. –

StyleCop предоставляет подсказки для кода и комментирования стиля. Предложения, которые он дает, соответствуют стилю документации MSDN.

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

источник

2010-06-29 18:03:06

Я скорее нашел StyleCop удобным напоминающим инструментом, когда я добавил/удалил параметр из метода и разнесся на обновление узлов ''. Из того, что я помню из своего последнего концерта, R # сделал это слишком в режиме реального времени. –

Другая опция: Resharper делает это в пользовательском интерфейсе. –

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

Я пишу < замечания > комментарий для включения информации Я хотел бы знать, была ли мне поручена отладка или повышение этой функции или класса. Примечание: это не заменяет необходимость в хороших встроенных комментариях. Но иногда общий обзор внутренней работы функции/класса очень полезен.

источник

2010-06-29 21:19:44 mikemanne

Не забудьте, что такое действительный XML. Например:

/// <Summary> 
/// Triggers an event if number of users > 1000 
/// </Summary>

(Ошибка: недопустимый XML).

источник

2010-06-29 21:24:42

Что такое наилучшая практика для документирования кода C# с комментариями XML?

ответ

Смежные вопросы