Почему /// блоки комментариев важны?

49

Кто-то однажды сказал, что мы должны поставить перед всеми нашими методами /// <summary>блоки комментариев (C #), но не объяснил, почему.

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

Есть ли веская причина использовать /// <summary>блоки комментариев в вашем коде?

Я обычно использую //комментарии все время, это просто /// <summary>блоки, которые мне интересны.

Рейчел
источник
1
Я не был уверен, были ли эти блоки комментариев личными предпочтениями или рекомендованными стандартами
Рэйчел
1
Я тоже так думаю.
Райан Хейс
30
Я думаю, что это именно тот вопрос, который здесь относится. Есть хороший шанс, что это будет закрыто для stackoverflow как субъективное.
паддислакер
Используйте блоки <summary>, если вы хотите создать документацию. Это имело бы смысл, если вы создаете API для использования другими. Выполнение этого для каждого метода является излишним и снижает вашу гибкость.
Макнейл

Ответы:

91

Используйте их как можно больше.

Да, это специальные комментарии, которые становятся документацией для метода. Содержимое <summary>тегов параметров и т. Д., Которые генерируются, отображаются в intellisense, когда вы или кто-то еще готовитесь к вызову вашего метода. По сути, они могут видеть всю документацию по вашему методу или классу, не обращаясь к самому файлу, чтобы выяснить, что он делает (или попытаться просто прочитать сигнатуру метода и надеяться на лучшее).

Райан Хейс
источник
22
+1 Абсолютно используй их. Вы будете удивлены, насколько полезно иметь их, если вы когда-нибудь повторно используете свои компоненты и имеете всю эту великолепную документацию, доступную в intellisense.
Уолтер
4
Кроме того, если вы используете Visual Studio и начинаете строку с /// непосредственно перед объявлением класса, метода или поля, VS сгенерирует для вас структуру документации XML - вам просто нужно заполнить ее. Я согласен, что она занимает много места на вашем экране, но я бы сказал, что это достойный компромисс. Кроме того, F # имеет лучшую поддержку (например, вам не нужно использовать <summary> и </ summary>, поскольку они «предполагаются»).
ShdNx
7
Поскольку этот ответ уже является лучшим выбором, я просто добавлю свой комментарий: Когда я узнал, что сводка используется для intellisense, и мои проекты выросли до своего текущего размера, я был очень рад, что нашел эту функцию. Помнить, для чего нужны мои методы и классы, стало огромной проблемой, и документирование кода с помощью этого механизма значительно упростило задачу, позволив мне сосредоточиться на новом коде и возможности повторного использования вместо того, чтобы пытаться вспомнить, что было сделано несколько месяцев назад.
Джелтон
3
Нужно только добавить, что эти комментарии не скомпилированы в dll, вы должны доставить связанный xml-файл вместе с dll.
Бенджол
Они полезны, но делают текущий класс очень нечитаемым. Я хотел бы, чтобы был другой способ, который не загромождает код.
Йерун ван Ланген
17

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

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

В последнем месте, где я работал, мы каждый вечер перестраивали документацию и размещали ее на внутренней домашней странице. Инициалы компании были MF, поэтому это было MFDN;)

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

Вы будете удивлены, насколько увлеклись документированием всего, когда начнете видеть его в формате MSDN!

Том Морган
источник
1
Ссылка на блог кажется мертвой (последнее сообщение 5 лет назад с разбитым html по всей странице), и местоположение проекта изменилось. У вас есть обновленная ссылка на Sandcastle?
12

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

В противном случае, серьезно подумайте о том, чтобы не использовать такие комментарии. Вы можете избежать их в большинстве случаев, изменив свой код следующим образом:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

в

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

в

    public bool IsAuthorizedToAccessResource( User user ) {

    }
azheglov
источник
11
Хотя я согласен с тем, что код должен самодокументироваться как можно чаще, я предлагаю по возможности использовать эти типы комментариев (и чаще, чем общие комментарии //). /// XML-комментарии предназначены для работы с IntelliSense, что может упростить разработку на месяцы, когда вы пытаетесь реализовать какую-то библиотеку, которую вы создали, и не совсем вспоминаете, как она работает.
Мэтт ДиТролио
2
И я думаю, что не только с точки зрения Intellisense, но и с точки зрения автоматического создания документации полезны xml-комментарии. Но, как и во всех комментариях, это имеет смысл только в том случае, если сами комментарии полезны и добавляют к самодокументированному коду.
Вайбхав
5
Я согласен с тем, что когда вы пишете публичные классы API или фреймворка, стандарт кодирования должен требовать, чтобы вы добавляли комментарии в код, чтобы можно было подключить IntelliSense и инструменты документации. Но это еще не весь код. Помимо этой проблемы, подход, который я здесь защищаю, заключается в том, что когда вы пытаетесь сделать свой код чище и яснее, сосредоточьтесь на самом коде, а не на комментарии, описывающем код.
ажеглов
3
@JYelton: ваш комментарий искажает мой ответ. Я имел в виду более описательные имена, но не обязательно более многословные, определенно не 60-символьный идентификатор для часто вызываемой публичной функции. Кроме того, у вас есть то, что кажется узкоспециализированной функцией, но она принимает очень общий тип данных (XmlDocument) - это один запах кода. Затем ваш 60-символьный идентификатор описывает «как», а не «что» - публичного метода. Это еще один запах. Основное сообщение: сначала подумайте о коде, а не о комментарии.
ажеглов
2
@JYelton Проблема с именем вашего метода не в том, что он носит описательный характер, а в том, что он описывает как минимум 2 отдельные операции и поэтому должен быть реорганизован как минимум в 2 независимых метода.
Нил
4

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

Тем не менее, я бы порекомендовал использовать их в любых общедоступных классах, методах и свойствах в API, библиотеке и т. Д. По крайней мере, они будут генерировать документы, которые помогут любому разработчику, использующему его, и не позволят вам иметь написать их.

Но в любом случае вы нарезаете его, сохраняете или удаляете.

Джон Макинтайр
источник
11
Именование - это одно, но перечисление ограничений на параметры или потенциально генерируемые исключения по-прежнему ценно.
Адам Лир
Да, я признаю, что у вас есть смысл, но в большинстве случаев ограничения параметров очевидны, не так ли?
Джон Макинтайр
Не уверен, что согласен с Джоном. С этой логикой ни один из методов .net framework не должен получать помощь Intellisense.
Вайбхав
1
@vaibhav - я сказал: «Я бы порекомендовал использовать их в любых общедоступных классах, методах и свойствах в API, библиотеке и т. д. ...» ... это охватило бы то, о чем вы говорите, не так ли?
Джон Макинтайр
1
@Джон - странно, я мог поклясться, что прочитал что-то совсем другое, когда написал этот комментарий. Потому что ваш второй абзац именно то, что я сказал в другом месте в этой теме. Итак, у меня должны быть камни в голове для написания этого комментария. Да, я согласен с этим.
Вайбхав
2

Если вы обнаружите, что вам нужно возвращаться и редактировать свои комментарии, чтобы они соответствовали новому коду, вы, возможно, в первую очередь делаете их неправильно. Элемент резюмирования должен содержать именно это - аннотацию - что и почему вы суммируете.

Описание того, как что-то работает в комментариях, нарушает СУХОЙ. Если ваш код недостаточно информативен, возможно, вам стоит вернуться и провести рефакторинг.

Никто
источник
1

Да, я их создал. [при создании новых систем с нуля]

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

Я обнаружил, что комментарии «Сводка» в конечном итоге имеют тенденцию не синхронизироваться с кодом. И как только я замечаю несколько комментариев с плохим поведением, я склонен терять веру во все комментарии к этому проекту - вы никогда не знаете, каким из них можно доверять.

Preets
источник
Однако устаревшие комментарии можно считать запахом кода, особенно на уровне сводки. Если другие разработчики меняют функции и не обновляют сводку того, что они делают, то можно утверждать, что они не документируют свою работу правильно.
rjzii
1

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

Это один из наиболее заметных способов документировать ваш код.

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

Абе Мисслер
источник
1

" Это должно быть использовано очень, как я;) "

Я играл с комментариями (///). Для класса вы можете просто сделать комментарий, как это

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Но для метода вы можете добавить больше с описанием параметров и возвращаемых типов.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Вы можете использовать ярлык для создания этого комментария (///+Tab).

Срикумар П
источник
0

используя их за исключением библиотек

Это время, когда они полезны. С включенной генерацией XML-документации и ссылкой на сборку без ее проекта в intellisense будет показана более подробная информация.

Но для внутренних органов текущего проекта они просто мешают.

Ричард
источник
0

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

Тодд Уильямсон
источник
0

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

Я не обязательно пишу роман - только основы, описание параметров и некоторые замечания (обычно, когда там происходит что-то «необычное» - обходной путь или другое дерьмо, которого я бы предпочел не иметь, но иметь нет выбора «на данный момент».) (Да, я знаю, что «на данный момент» может длиться годами.)

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

MetalMikester
источник