Советы по комментированию XML для программирования на C# [закрыто]
Доброе утро, день, вечер или ночь (в зависимости от вашего часового пояса).
Это всего лишь общий вопрос о XML-комментариях в C#. Я никогда не был очень большим в комментировании моих программ, я всегда был более подробным именем переменной/свойства/метода и позволял коду говорить за себя. Я пишу комментарии, если я кодирую что-то довольно запутанное, но по большей части я не пишу много комментариев.
Я читал кое-что о XML-комментарии в .NET, Sandcastle и построителе файлов справки на codeplex, и это привело меня к желанию документировать мой код и генерировать хорошую, полезную документацию для тех, кто должен копаться в моем коде, когда меня больше нет.
мой вопрос касается стандартов и конвенций. Есть ли руководство по" хорошему " комментарию XML? Следует ли комментировать каждую переменную и свойство? Каждый метод? Я просто ищу советы о том, как писать хорошие комментарии, которые будут скомпилирован sandcastle в хорошую документацию, чтобы другие программисты не проклинали мое имя, когда им придется работать над моим кодом.
заранее спасибо за Ваши советы и предложения, Скотт Vercuski
6 ответов
лично мы удостоверяемся, что каждый открытый и защищенный метод имеет комментарии XML. Он также предоставит вам Intellisense, а не только справочную документацию конечного пользователя. В прошлом мы также включали его в частные декларации, но не считаем, что это 100% требуется, если методы короткие и точечные.
Не забывайте, что есть инструменты, чтобы сделать вас XML комментируя задачи проще:
- GhostDoc - комментарий наследование и надстройка шаблонов.
- Sandcastle Help File Builder - редактирует проекты Sandcastle через GUI, может быть запущен из командной строки (для автоматизации сборки), и может редактировать MAML для справки темы, не производные от кода. (Версия 1.8.0.0 alpha очень стабильна и очень улучшена. Использовали его около месяца, более 1.7.0.0)
комментарии очень часто устарели. Это всегда было проблемой. Мое правило : чем больше вам нужно работать, чтобы изменить комментарий, тем быстрее этот комментарий будет устаревшим.
комментарии XML отлично подходят для разработки API. Они очень хорошо работают с Intellisens, и они могут заставить вас создать справочный документ HTML в кратчайшие сроки.
но это не бесплатно: поддерживать их будет сложно (посмотрите на любой нетривиальный пример, вы поймете, что я имею в виду), поэтому они будет иметь тенденцию устаревать очень быстро. В результате просмотр XML-комментариев должен быть добавлен в ваш обзор кода в качестве обязательной проверки и эта проверка должна выполняться каждый раз при обновлении файла.
Ну, так как это дорого поддерживать, так как много не частных символов (в разработке без API) используются только 1 или 2 классами, и поскольку эти символы часто являются самоочевидными, я бы никогда не применял правило, говорящее, что каждый не частный символ должен быть XML прокомментированный. это будет перебор и conterproductive. То, что вы получите то, что я видел во многих местах : почти пустые комментарии XML ничего добавлять к имени символы. И код, который просто немного менее читаем...
думаю, что очень-очень важная направляющая строка о комментариях в нормальном (не API) коде не должна быть о как они должны быть написаны а о что они должны содержать. Много разработчиков еще не знаю что писать. Описание того, что следует Прокомментировать, с примерами, будет лучше для вашего кода, чем просто : "используйте XML-комментарии для каждого не частного символа.".
Я документирую открытые классы и открытые/защищенные члены этих классов.
Я не документирую частные или внутренние члены или внутренние классы. Следовательно, переменные (я думаю, вы имеете в виду поля), потому что они частные.
цель создания документации для разработчика, который не имеет доступа к исходному коду.
попытайтесь поместить некоторые примеры, где использование не очевидно.
Я очень редко комментирую переменные метода и столь же редко поля (поскольку они обычно покрываются свойством или просто не существуют при использовании автоматически реализованных свойств).
обычно я стараюсь добавлять содержательные комментарии ко всем общедоступным / защищенным членам, что удобно, так как если вы включаете комментарии xml во время сборки, вы получаете автоматические предупреждения за отсутствующие комментарии. В зависимости от сложности, я не могу заполнить каждую деталь-т. е. если это 100% очевидно, что каждый параметр и to do (т. е. нет специальной логики, и есть только 1 логический способ интерпретации переменных), то I может лениться и не добавляйте комментарии о параметрах.
но я, конечно, пытаюсь описать, какие методы, типы, свойства и т. д. представляют/делают.
мы документируем открытые методы / свойства / etc в наших библиотеках. В рамках процесса сборки мы используем NDoc для создания веб-ссылки, подобной MSDN. Это было очень полезно для быстрой справки и поиска.
Он также отлично подходит для IntelliSense, особенно с новыми членами команды или, как вы сказали, когда автора нет.
Я согласен, что код, в общем, должен быть понятным. XML documention, для меня, больше о ссылке и поиске, когда вы этого не делаете откройте источник.
лично мое мнение, не комментируя. Комментировать опасно. Поскольку в промышленности мы всегда обновляем код (потому что бизнес и требования всегда меняются), но редко меняемся, мы обновляем наши комментарии. Это может ввести в заблуждение программистов.