Требуется ли «Получить или установить ...» в документации по свойствам в формате 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 извлекается, чтобы получить доступ к одному из этих свойств, нет указания, в какие из них можно записывать, читать или как:

Аналогично, при просмотре документации мы также не совсем уверены:

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

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 и Set. Если бы у вас был частный сеттер, это было бы очевидно, поскольку у вас было бы частное ключевое слово.

Комментарии должны повышать ценность, а не просто комментировать версию кода.