Требуется ли «Получить или установить ...» в документации по свойствам в формате XML?

19

Я ищу рекомендацию лучшей практики для комментариев 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 использует первую форму, поэтому кажется, что это подразумеваемое соглашение. Но я думаю, что второй лучше по причинам, которые я изложил.

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

Я буду признателен за любые идеи или ссылки на официальные рекомендуемые практики.

Tomas
источник
Честно говоря, единственное, что дает мне комментарий, которого нет в коде (при условии, что это член User), это то, что идентификатор уникален. так что ничего из этого не является «необходимым».
JK.
@Tomas - вы установили плагин GhostDoc ? он будет генерировать хорошие XML-комментарии для вас, если вы начнете использовать хорошие имена свойств и автоматически добавите gets or setsили в getsзависимости от методов доступа к свойствам.
Тревор Пилли
@Trevor - он у меня установлен. Я просто думал, должен ли я изменить его шаблоны и удалить «Получить или установить» или нет :). Это отличный плагин, хотя.
Томас
Добро пожаловать в мир недокументированных .
полковник Паник

Ответы:

28

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

введите описание изображения здесь

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

введите описание изображения здесь введите описание изображения здесь введите описание изображения здесь

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

введите описание изображения здесь

Майк
источник
Спасибо за подробный ответ. Я думаю, что это, к сожалению, ограничения IDE Visual Studio. Я думал об этом, и я думаю, что intellisense может показать вам, какие свойства, например, только getв текущем контексте. Не очень удобно сгибать документацию под конкретную среду разработки. Тем не менее, я думаю, что Visual Studio и C # настолько тесно связаны, что это может быть правильным решением.
Томас
1
@ Томас Я согласен, что Visual Studio должна делать больше различий. Это, конечно, радо дать мне красную волнистую линию, как только я неправильно использую собственность.
Майк
2

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 (например).

NikolaiDante
источник
2

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

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

CLandry
источник
1

Я был бы счастлив с более подробной версией.

Другое похоже на комментарий «счетчика приращений» после, ну, в общем, приращения переменной счетчика.

Очевидно, что есть Get и Set. Если бы у вас был частный сеттер, это было бы очевидно, поскольку у вас было бы частное ключевое слово.

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

Ozz
источник