Чи потрібні "Отримати або встановлює .." в документації XML про властивості?

Я шукаю рекомендації щодо найкращої практики для коментарів XML у C #. Коли ви створюєте властивість, схоже, що очікувана XML-документація має такий вигляд:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Але оскільки підпис властивості вже говорить вам про те, які операції доступні для зовнішніх клієнтів класу (в даному випадку це і те, getі інше set), я вважаю, що коментарі занадто балакачі і, можливо, цього буде достатньо:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft використовує першу форму, тому здається, що це умовна умова. Але я вважаю, що другий кращий з тих моїх причин.

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

Я буду вдячний за будь-які ідеї чи посилання на рекомендовані офіційні практики.

Підпис може вказувати іншим фрагментам коду, які операції доступні; однак вони не чітко показані кодеру, оскільки він або вона працює, а документація XML призначена для споживання людьми, а не компілятором.

Візьмемо для прикладу цей клас:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Коли intellisense підтягується для доступу до однієї з цих властивостей, немає вказівки, з яких можна записати, прочитати або обидва:

Так само при перегляді документації ми також не зовсім впевнені:

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

StyleCop використовує Gets or Sets ...позначення, які застосовує за допомогою правила SA1623 .

На пов’язаній сторінці перелічено ще один випадок, який ви не перелічили:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

Інший варіант, який ви перераховуєте, був би.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

проти

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Який не буде надавати інформацію про натяк Intellisense , що властивість тільки для читання, ви можете придумати конвенції цього випадку, але Gets ..., Gets or Sets...робите роботу добре ІМО.

Існують також інші варіанти, перелічені в правилі StyleCop, які зрозумілі за допомогою, Gets or Sets...але можуть бути без них.

Крім того, при створенні документації з чогось типу Doxygen або Sandcastle повна нотація буде краще документувати API (наприклад).

Єдиний раз, коли я додаю інформацію про отримання та налаштування властивості у коментарях XML - це коли він не веде себе так, як очікувалося (пряме отримання загального доступу та встановлення).

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

Я був би щасливішим з більш детальною версією.

Інший - це як мати коментар до "лічильника приросту" після, ну, збільшуючи змінну лічильника.

Очевидно, що є Get and Set. Якби у вас був приватний сетер, це було б очевидно, як і приватне ключове слово.

Коментарі повинні додавати значення, а не лише коментувати версію того, що насправді є кодом.