XML Комментарий подсказок для [закрытого] программирования C#

Я документирую общедоступные классы и Общедоступных/Защищать членов тех классов.

я не документирую частных или внутренних участников или внутренние классы. Следовательно переменные (я думаю Вы поля осредненных величин), потому что они являются частными.

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

Индевор для размещения некоторых примеров, где использование не очевидно.

Я очень редко комментирую переменные метода и одинаково редко поля (так как они обычно покрываются свойством или просто не существуют, если использование автореализовало свойства).

Обычно я очень стараюсь добавить значимые комментарии ко всем общедоступным/защищать участникам, который удобен, с тех пор при включении комментариев xml во время сборки Вы получаете автоматические предупреждения для пропавших без вести комментариев. В зависимости от сложности я не мог бы заполнить каждую деталь - т.е. если на 100% очевидно, что каждый параметр имеет , чтобы сделать (т.е. нет никакой специальной логики, и существует только 1 логический способ интерпретировать переменные), затем я мог бы становиться ленивым и не добавлять комментарии о параметрах.

, Но я, конечно, пытаюсь описать, какие методы, типы, свойства, и т.д. представляют/.

Мы документируем общедоступные методы/свойства/и т.д. на наших библиотеках. Как часть процесса сборки мы используем NDoc для создания подобной MSDN веб-ссылки. Это было очень полезно для справочника и поиска.

Это является также большим для Intellisense, особенно с новыми членами команды или, как Вы сказал, когда исходный автор ушел.

я соглашаюсь, что код, в целом, должен быть очевидным. XML documention, мне, больше о ссылке и поиске, когда у Вас нет источника открытым.

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

Комментарии XML отлично подходят для разработки API. Они довольно хорошо работают с Intellisens, и с их помощью вы можете мгновенно создать справочный документ HTML.

Но это не бесплатно: поддерживать их будет сложно (посмотрите на любой нетривиальный пример, вы поймете, что я имею в виду) , поэтому они, как правило, очень быстро устаревают. В результате просмотр комментариев XML должен быть добавлен к обзору кода в качестве обязательной проверки , и эта проверка должна выполняться каждый раз при обновлении файла.

Что ж, поскольку это дорого в обслуживании, поскольку множество неперсонализированных символов (в разработке без API) используются только 1 или 2 классами, и поскольку эти символы часто говорят сами за себя, я бы никогда не стал применять правило, согласно которому каждый не-частный символ должен быть прокомментирован XML. Это было бы излишним и вредным . Вы получите то, что я видел во многих местах: почти пустые комментарии XML, ничего не добавляющие к имени символа. И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

Я бы никогда не стал применять правило, согласно которому каждый не-частный символ должен быть прокомментирован XML. Это было бы излишним и вредным . Вы получите то, что я видел во многих местах: почти пустые комментарии XML, ничего не добавляющие к имени символа. И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

Я бы никогда не стал применять правило, согласно которому каждый не-частный символ должен быть прокомментирован XML. Это было бы излишним и вредным . Вы получите то, что я видел во многих местах: почти пустые комментарии XML, ничего не добавляющие к имени символа. И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

Это было бы излишним и вредным . Вы получите то, что я видел во многих местах: почти пустые комментарии XML, ничего не добавляющие к имени символа. И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

Это было бы излишним и вредным . Вы получите то, что я видел во многих местах: почти пустые комментарии XML, ничего не добавляющие к имени символа. И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

И код, который немного менее читабелен ...

Я думаю, что очень, очень важное руководство по комментариям в нормальном (не API) коде не должно быть о КАК они должно быть написано но о ЧТО они должны содержать . Многие разработчики до сих пор не знают , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

не знаю , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

не знаю , что писать. Описание того, что следует прокомментировать, с примерами лучше подойдет для вашего кода, чем просто: «Используйте XML-комментарии для каждого не личного символа».

Лично мое мнение - избегать комментариев. Комментировать опасно. Поскольку в отрасли мы всегда обновляем код (потому что бизнес и требования всегда меняются), но меняются редко, мы обновляем наши комментарии. Это может ввести программистов в заблуждение.