Question

I am a relatively new developer and have been assigned the task of documenting code written by an advanced C# developer. My boss told me to look through it, and to document it so that it would be easier to modify and update as needed.

My question is: Is there a standard type of Documentation/Comment structure I should follow? My boss made it sound like everyone knew exactly how to document the code to a certain standard so that anyone could understand it.

I am also curious if anyone has a good method for figuring out unfamiliar code or function uncertainty. Any help would be greatly appreciated.

Answer 1

The standard seems to be XML Doc (MSDN Technet article here).

You can use /// at the beginning of each line of documentation comments. There are standard XML style elements for documenting your code; each should follow the standard <element>Content</element> usage. Here are some of the elements:

<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.