Правила/рекомендации по документированию кода С#?

Ответ 1

Стандарт представляется XML Doc (статья MSDN Technet здесь).

Вы можете использовать /// в начале каждой строки комментариев к документации. Существуют стандартные элементы стиля XML для документирования вашего кода; каждый из них должен соответствовать стандарту <element>Content</element>. Вот некоторые из элементов:

<c>               Used to differentiate code font from normal text 
                    <c>class Foo</c>
<code>
<example>
<exception>
<para>            Used to control formatting of documentation output. 
                    <para>The <c>Foo</c> class...</para>
<param>
<paramref>        Used to refer to a previously described <param>  
                    If <paramref name="myFoo" /> is <c>null</c> the method will...
<remarks>
<returns>
<see>             Creates a cross-ref to another topic. 
                     The <see cref="System.String" /><paramref name="someString"/>
                     represents...

<summary>         A description (summary) of the code you're documenting.                     

Ответ 2

Похоже, вы действительно набрали короткую соломинку.

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

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

• Логика комментариев, которая неясна (и рассматривает рефакторинг)
• Только методы/свойства Xml-Doc, которые могут быть допрошены (или, если вам нужно предоставить более подробный обзор)
• Если ваши комментарии превышают длину содержащего метода/класса, вы можете подумать о многословности комментариев или даже рассмотреть рефакторинг.
• Попробуйте представить, что новый разработчик встречает этот код. Какие вопросы они задали бы?

Похоже, ваш босс ссылается на логику комментариев (скорее всего, чтобы вы могли ее понять) и с помощью комментариев xml-doc.

Если вы еще не использовали комментарии xml-doc, проверьте эту ссылку, которая должна дать вам небольшое руководство по использованию и, при необходимости,.

Если ваша рабочая нагрузка выглядит немного тяжелой (т.е. много кода для комментариев), у меня есть хорошие новости для вас - есть отличный плагин для Visual Studio, который может помочь вам в комментариях xml-doc. GhostDoc может значительно упростить методы/классы комментариев xml-doc (но не забудьте изменить текст заполнителя по умолчанию он вставляет там!)

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

Ответ 3

Я подозреваю, что ваш босс ссылается на следующие комментарии к документации XML.

Комментарии к документации XML (руководство по программированию на С#)

Ответ 4

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

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

Чтобы быстро и последовательно выполнить вашу документацию, вы можете попробовать мою надстройку для Visual Studio, AtomineerUtils Pro Documentation. Это поможет в запутанной работе по созданию и обновлению комментариев, убедитесь, что комментарии полностью сформированы и синхронизированы с кодом, и позвольте сосредоточиться на самом коде.

Что касается того, как работает код...

Надеемся, что имена классов, методов, параметров и переменных будут описательными. Это должно дать вам неплохую отправную точку. Затем вы можете взять один метод или класс за раз и определить, считаете ли вы, что код внутри него обеспечивает то, что, по вашему мнению, означает именование. Если есть единичные тесты, это даст хорошее представление о том, что программист ожидал, что код будет делать (или обрабатывать). Независимо от того, попробуйте написать несколько (более) единичных тестов для кода, потому что, думая о специальных случаях, которые могут нарушить код, и выясняя, почему код не прошел некоторые из ваших тестов, вы получите хорошее представление о том, что он делает и как он делает это. Затем вы можете увеличить основную документацию, которую вы написали, с более полезными подробностями (может ли этот параметр быть нулевым, какой диапазон значений является законным? Каким будет возвращаемое значение, если вы передаете пустую строку? И т.д.)

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

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

Я бы рекомендовал использовать XML-документацию (см. другие ответы), поскольку это сразу же подхватывает Visual Studio и используется для справки intellisense. Тогда любой, кто пишет код, который вызывает ваши классы, получит помощь во всплывающих подсказках по мере ввода кода. Это большой бонус при работе с командой или большой кодовой базой, но многие компании/программисты просто не понимают, чего им не хватает, ударяя свои (недокументированные) камни вместе в темные века: -)

Ответ 5

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

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

Надеюсь, что это поможет - удачи!