Я ищу рекомендацию лучшей практики для комментариев 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 использует первую форму, поэтому кажется, что это подразумеваемое соглашение. Но я думаю, что второй лучше по причинам, которые я изложил.
Я понимаю, что этот вопрос отлично подходит для того, чтобы его пометили как неконструктивный, но количество свойств, которые нужно прокомментировать, огромно, и поэтому я считаю, что этот вопрос имеет право быть здесь.
Я буду признателен за любые идеи или ссылки на официальные рекомендуемые практики.
gets or sets
или вgets
зависимости от методов доступа к свойствам.Ответы:
Подпись может сообщать другим частям кода, какие операции доступны; однако, они не ясно показаны кодеру, когда он или она работает, и документация XML предназначена для людей, а не для компилятора.
Возьмите этот класс, например:
Когда intellisense извлекается, чтобы получить доступ к одному из этих свойств, нет указания, в какие из них можно записывать, читать или как:
Аналогично, при просмотре документации мы также не совсем уверены:
Таким образом мы добавим получает или устанавливает , получает или наборы , чтобы сделать его легче на программиста при написании кода. Конечно, было бы не написать большой блок кода, который считывает и обрабатывает некоторые данные, только чтобы выяснить, что вы не можете записать эти данные обратно в свойство, как ожидалось.
источник
get
в текущем контексте. Не очень удобно сгибать документацию под конкретную среду разработки. Тем не менее, я думаю, что Visual Studio и C # настолько тесно связаны, что это может быть правильным решением.StyleCop использует
Gets or Sets ...
нотацию, которую он применяет в правиле SA1623 .На связанной странице перечислены другие случаи, которых вы не указали:
Другой вариант, который вы перечислите, будет.
против
Который не будет предоставлять информацию о намеке Intellisense , что свойство только для чтения, вы можете придумать конвенции этого случая, но
Gets ...
,Gets or Sets...
делаете работу хорошо имо.В правиле StyleCop перечислены и другие варианты, которые понятны при использовании,
Gets or Sets...
но могут отсутствовать.Также при создании документации из чего-то вроде Doxygen или Sandcastle полная нотация лучше документирует API (например).
источник
Единственный раз, когда я добавляю информацию о получении и настройке свойства в XML-комментариях, это когда он не ведет себя должным образом (прямое публичное получение и установка).
Если они являются частными или содержат дополнительную логику, я упоминаю их, в противном случае я просто документирую намерение свойства.
источник
Я был бы счастлив с более подробной версией.
Другое похоже на комментарий «счетчика приращений» после, ну, в общем, приращения переменной счетчика.
Очевидно, что есть Get и Set. Если бы у вас был частный сеттер, это было бы очевидно, поскольку у вас было бы частное ключевое слово.
Комментарии должны повышать ценность, а не просто комментировать версию кода.
источник