记录C#代码的规则/指南？

Question

我是一个相对较新的开发人员,并被分配了记录由高级C#开发人员编写的代码的任务.我的老板告诉我要仔细查看,并记录下来,以便根据需要更容易修改和更新.

我的问题是:我应该遵循标准类型的文档/评论结构吗？我的老板听起来好像每个人都知道如何将代码记录到某个标准,以便任何人都能理解它.

我也很好奇是否有人有一个很好的方法来找出不熟悉的代码或功能不确定性.任何帮助将不胜感激.

Answer 1

该标准似乎是XML文档(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.