Ндок по свойствам лучшей практики?
Мой менеджер проекта на прошлой неделе намекнул на использование ndoc для свойств в классе. Это то, что должно быть сделано? Это считается лучшей практикой, чтобы сделать это или нет? В настоящее время я расширяю весь свой ndoc для раздела проекта, над которым я работаю, но не знаю, насколько мне нужно углубиться в него. Я, конечно, предоставил резюме, параметры, возвраты и замечания классу и каждому методу, но свойства тоже требуют ndoc?
3 ответа
Публичная собственность - это контракт с внешним миром, я думаю, что они должны быть задокументированы.
Внутренние свойства будут использоваться только в одной сборке, поэтому вы можете избежать их документирования.
Защищенные свойства будут использоваться только в производных классах (внутренних или общедоступных), поэтому они могут нуждаться в некоторой документации.
Частные свойства будут использоваться только в самом классе, так что, опять же, вы можете сойти с рук.
Обратите внимание, что "обойтись без документирования" подсказывает, что я думаю по этому поводу: вам следует документировать. В то же время я понимаю, что иногда нужно делать одно или другое...
Возможно, вы должны спросить об этом на http://programmers.stackexchange.com/
Открытые свойства обязательно должны быть задокументированы, независимо от того, использует ли выбранный вами документооборот GhostDoc, NDoc или что-то еще. XML-комментарии об открытых свойствах и методах отображаются в Intellisence, когда люди его используют, поэтому нет причин не добавлять туда что-либо. Даже если имя свойства объясняет, что оно делает, очень приятно иметь там XML-комментарии, чтобы подтвердить это. В коде много ошибок, поэтому любезно сообщить людям, использующим ваш код, что они не идут в один.
Частная собственность может пойти в любую сторону. Я бы не стал называть это лучшей практикой, поскольку для того, чтобы увидеть комментарии, которые вы должны присутствовать в классе, вы можете просто посмотреть на его использование тривиально. Тем не менее, я все еще помещаю комментарии XML в частные свойства, если ни для кого, то для себя. Вы никак не сможете вспомнить, что вы делали через 6 месяцев, и любые структурные комментарии, которые вы можете добавить, облегчат вам выбор с того места, где вы остановились.
Как и любые другие члены, значение свойств должно быть задокументировано. Это должно включать не только то, что делает свойство или для чего оно может использоваться, но также его начальное значение, особые случаи (например, значения, которые не должны быть назначены; значения, которые могут вызвать исключение или автоматически заменяются другими значениями), так как а также возможные последствия и цель переопределения свойства в производном классе, где это возможно.