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

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

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

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

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

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

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

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

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

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

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

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

Если ваш стандарт кодирования требует, чтобы вы использовали такие комментарии (а стандарт кодирования для 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 ) {

    }

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

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

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

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

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

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

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

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

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

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

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

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

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

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).

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

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

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

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

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

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

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