Чому важливі /// блоки коментарів?

Хтось одного разу сказав, що ми повинні префіксувати всі наші методи /// <summary>блоками коментарів (C #), але не пояснив чому.

Я почав їх використовувати і виявив, що вони мене дуже дратували, тому перестав їх використовувати, за винятком бібліотек та статичних методів. Вони громіздкі, і я завжди забуваю їх оновлювати.

Чи є якісь вагомі причини використовувати /// <summary>блоки коментарів у вашому коді?

Я зазвичай постійно користуюся //коментарями, /// <summary>мені це було цікаво лише про ті блоки.

Використовуйте їх якомога більше.

Так, це спеціальні коментарі, які стають документацією для методу. Вміст <summary>, теги параметрів тощо, що генеруються, відображаються в інтелігенції, коли ви або хтось інший готується зателефонувати на ваш метод. Вони по суті можуть бачити всю документацію для вашого методу чи класу, не потребуючи самого файлу, щоб зрозуміти, що він робить (або спробувати просто прочитати підпис методу та сподіватися на найкраще).

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

Крім того, використовуйте їх спільно з 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, бібліотеці тощо ... Принаймні, вони генерують документи, щоб допомогти будь-якому розробнику, який використовує його, і заважатиме вам мати писати їх.

Але все одно ви їх нарізаєте, підтримуєте або видаляєте.

Якщо ви виявите, що вам доведеться продовжувати повертатися назад і редагувати свої коментарі, щоб відповідати новому коду, ви можете зробити їх неправильно в першу чергу. Елемент резюме повинен містити саме те - підсумок - що і чому те, що ви резюмуєте.

Описуючи, як щось працює в коментарях, порушує DRY. Якщо ваш код недостатньо самостійний для опису, можливо, вам слід повернутись та рефактор.

Так, я їх створив. [при створенні нових систем з нуля]

Ні, я ніколи від них не вигравав. [під час роботи над існуючими системами, які потребували обслуговування]

Я виявив, що коментарі "Підсумки" з часом не мають сили з кодом. І як тільки я помічаю кілька погано поводяться коментарів, я, як правило, втрачаю віру в усі коментарі до цього проекту - ви ніколи не знаєте, кому з них довіряти.

Забути щось зробити - це не погана ідея. Забути оновити будь-яку документацію є. Я вважаю, що це дуже корисно в моєму програмуванні, і люди, які успадковують мій код, вдячні їм за те, що вони.

Це один із найпомітніших способів документувати свій код.

Болісно знайти вихідний код, щоб прочитати вбудовану документацію або викопати документ, який перевершує те, що робить код. Якщо у вас може з’явитися щось корисне, що з’явиться через інтелект, люди вас люблять.

" Її треба дуже використовувати, як я;) "

Раніше я грав із коментарями (///). Для класу ви можете просто зробити такий коментар

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 Документації, і посилання на збірку, без її проекту, буде демонструвати більше деталей у інтелігенції.

Але для внутрішніх справ поточного проекту вони просто заважають.

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

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

Я не обов'язково пишу роман - лише основи, опис параметрів та деякі зауваження (зазвичай, коли там відбувається щось "незвичне" - обхід чи інша лайна, якої я б не мав там, але маю немає вибору "поки що".) (Так, я знаю, що "наразі" може тривати роки.)

Мене сильно дратує коментований код. Консультант написав початкову версію одного з наших компонентів і нічого не коментував, і вибір його імен залишається бажатим тут і там. Йому вже більше року, і ми все ще розбираємо його речі (окрім роботи над власними речами.)