Кто-то однажды сказал, что мы должны поставить перед всеми нашими методами /// <summary>
блоки комментариев (C #), но не объяснил, почему.
Я начал их использовать и обнаружил, что они меня немного раздражают, поэтому перестал их использовать, за исключением библиотек и статических методов. Они громоздкие, и я всегда забываю обновить их.
Есть ли веская причина использовать /// <summary>
блоки комментариев в вашем коде?
Я обычно использую //
комментарии все время, это просто /// <summary>
блоки, которые мне интересны.
Ответы:
Да, это специальные комментарии, которые становятся документацией для метода. Содержимое
<summary>
тегов параметров и т. Д., Которые генерируются, отображаются в intellisense, когда вы или кто-то еще готовитесь к вызову вашего метода. По сути, они могут видеть всю документацию по вашему методу или классу, не обращаясь к самому файлу, чтобы выяснить, что он делает (или попытаться просто прочитать сигнатуру метода и надеяться на лучшее).источник
Да, обязательно используйте их для всего, что вы хотите сохранить или можете поделиться им.
Кроме того, используйте их вместе с Sandcastle и конструктором файлов справки Sandcastle , который принимает вывод XML и превращает его в красивую документацию в стиле MSDN.
В последнем месте, где я работал, мы каждый вечер перестраивали документацию и размещали ее на внутренней домашней странице. Инициалы компании были MF, поэтому это было MFDN;)
Обычно я просто создаю файл .chm, которым легко обмениваться.
Вы будете удивлены, насколько увлеклись документированием всего, когда начнете видеть его в формате MSDN!
источник
Если ваш стандарт кодирования требует, чтобы вы использовали такие комментарии (а стандарт кодирования для API или фреймворка может требовать этого), то у вас нет выбора, вы должны использовать такие комментарии.
В противном случае, серьезно подумайте о том, чтобы не использовать такие комментарии. Вы можете избежать их в большинстве случаев, изменив свой код следующим образом:
в
в
источник
Ваше наименование класса, метода и свойства должно быть самоочевидным, поэтому, если вам это нужно, это, вероятно, запах.
Тем не менее, я бы порекомендовал использовать их в любых общедоступных классах, методах и свойствах в API, библиотеке и т. Д. По крайней мере, они будут генерировать документы, которые помогут любому разработчику, использующему его, и не позволят вам иметь написать их.
Но в любом случае вы нарезаете его, сохраняете или удаляете.
источник
Если вы обнаружите, что вам нужно возвращаться и редактировать свои комментарии, чтобы они соответствовали новому коду, вы, возможно, в первую очередь делаете их неправильно. Элемент резюмирования должен содержать именно это - аннотацию - что и почему вы суммируете.
Описание того, как что-то работает в комментариях, нарушает СУХОЙ. Если ваш код недостаточно информативен, возможно, вам стоит вернуться и провести рефакторинг.
источник
Да, я их создал. [при создании новых систем с нуля]
Нет, я никогда не пользовался ими. [при работе на существующих системах, которые нуждались в обслуживании]
Я обнаружил, что комментарии «Сводка» в конечном итоге имеют тенденцию не синхронизироваться с кодом. И как только я замечаю несколько комментариев с плохим поведением, я склонен терять веру во все комментарии к этому проекту - вы никогда не знаете, каким из них можно доверять.
источник
Забыть что-то сделать не значит, что это плохая идея. Забыть обновить любую документацию есть. Я нашел это очень полезным в моем программировании, и люди, которые наследуют мой код, благодарны, что они есть.
Это один из наиболее заметных способов документировать ваш код.
Трудно найти исходный код, чтобы прочитать встроенную документацию или выкопать документ, в котором рассказывается о том, что делает код. Если вы можете получить что-то полезное через интеллект, тогда люди будут любить вас.
источник
Я играл с комментариями (///). Для класса вы можете просто сделать комментарий, как это
Но для метода вы можете добавить больше с описанием параметров и возвращаемых типов.
Вы можете использовать ярлык для создания этого комментария
(///+Tab)
.источник
Это время, когда они полезны. С включенной генерацией XML-документации и ссылкой на сборку без ее проекта в intellisense будет показана более подробная информация.
Но для внутренних органов текущего проекта они просто мешают.
источник
Я использую их, но, как говорили некоторые другие, не всегда. Для небольших методов они могут быть больше, чем код, который они объясняют. Они наиболее полезны для создания документации, которая может быть предоставлена людям, плохо знакомым с системой, чтобы у них было что-то, на что можно ссылаться при ее изучении. Несмотря на то, что, как программисты, мы обычно можем понять, для чего нужен какой-то код, но было бы неплохо иметь комментарии, которые помогут нам и будут действовать как опора. Если он должен быть записан где-то, то в коде есть место, где он, скорее всего, останется обновленным (более вероятно, чем какой-нибудь документ Word, плавающий вокруг).
источник
Я использую эквивалент в VB (поскольку они не позволяют мне использовать C # - очевидно, это слишком сложно ... без комментариев.) Я нахожу их очень удобными. Большую часть времени я жду, пока процедура или функция не будут в значительной степени завершены, прежде чем вводить их, хотя бы для того, чтобы избежать необходимости изменять комментарии - или чтобы они были "не синхронизированы".
Я не обязательно пишу роман - только основы, описание параметров и некоторые замечания (обычно, когда там происходит что-то «необычное» - обходной путь или другое дерьмо, которого я бы предпочел не иметь, но иметь нет выбора «на данный момент».) (Да, я знаю, что «на данный момент» может длиться годами.)
Я сильно раздражен некомментированным кодом. Консультант написал первоначальную версию одного из наших компонентов и ничего не комментировал, а его выбор имен оставлял желать лучшего здесь и там. Его больше года не было, и мы все еще разбираемся с его вещами (в дополнение к работе над нашими вещами).
источник