Question

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

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

如果有人有一个很好的方法可以找出不熟悉的代码或功能不确定性，我也很好奇。任何帮助将不胜感激。

Answer 1

标准似乎是XML Doc（MSDN Technet文章here）。

您可以在每行文档评论的开头使用///。有标准的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.

Answer 2

听起来你真的最后得到了短暂的吸管。

不幸的是，我认为你偶然发现了一个比较有争议的软件开发主题。在必要时，评论可被视为非常有用，并且在错误使用时会被视为不必要的瑕疵。你必须要小心，并仔细地决定在哪里。

就评论实践而言，通常取决于公司或开发商。我喜欢使用的一些常见规则是：

评论逻辑不明确（并考虑重构）
只有可以质疑的Xml-Doc方法/属性（或者，如果您需要提供更详细的概述）
如果您的评论超出了包含方法/类的长度，您可能需要考虑评论详细程度，甚至考虑重构。
尝试并想象一下遇到此代码的新开发人员。他们会问什么问题？

听起来你的老板指的是评论逻辑（最有可能让你开始理解它）并使用xml-doc评论。

如果您之前没有使用过xml-doc评论，请查看this link，它可以为您提供有关使用的指导和适当的指导。

如果您的工作负载看起来有点沉重（即需要注释的代码很多），我有一些好消息 - Visual Studio有一个很好的插件可以帮助您查找xml-doc注释。 GhostDoc 可以使xml-doc注释方法/类等更容易（但请记住更改它在那里插入的默认占位符文本！）

请记住，在进行ghostdoc狂欢之前，您可能需要与老板核实他想要记录的代码部分。

Answer 3

我怀疑你的老板是指以下XML文档评论。

XML Documentation Comments (C# Programming Guide)

Answer 4

有点担心原来的程序员没有费心去做他工作中最重要的部分之一。然而，那里有很多可怕的“好”程序员，所以这并不是那么不寻常。

然而，让你记录代码也是一个非常好的培训机制 - 你必须阅读和理解代码，然后才能记下它的作用，并且获得系统知识，你无疑会选择从其他程序员所做的好事（和坏事）中得到一些提示和技巧。

为了帮助您快速一致地完成文档编制，您可能希望尝试使用Visual Studio的加载项AtomineerUtils Pro Documentation。这将有助于创建和更新注释的无聊工作，确保注释完全形成并与代码同步，并让您专注于代码本身。

关于如何运作代码......

希望类，方法，参数和变量名称是描述性的。这应该给你一个很好的起点。然后，您可以一次使用一个方法或类，并确定您是否认为其中的代码提供了您认为命名所暗示的内容。如果有单元测试，那么这些将很好地指示程序员期望代码执行（或处理）的内容。无论如何，尝试为代码编写一些（更多）单元测试，因为考虑可能会破坏代码的特殊情况，并找出代码导致某些测试失败的原因，这将使您很好地理解它的作用和方式它做到了。然后你可以用更有用的细节扩充你写的基本文档（这个参数可以为null吗？什么值的值是合法的？如果你传入一个空字符串，返回值是什么？等等）

这可能令人生畏，但如果你先从小类和方法开始（例如，只返回一个名称字符串的Name属性），你将熟悉周围的代码，并能够逐步前进到更复杂的类和方法。

一旦为类编写了基本代码文档，您就应该编写外部概述文档，该文档描述了整个系统的功能。然后你就可以开始研究代码库的这一部分了，因为你会理解它们是如何组合在一起的。

我建议使用XML文档（请参阅其他答案），因为Visual Studio会立即将其用于智能感知帮助。然后，编写调用类的代码的任何人都会在键入代码时获得工具提示的帮助。在与团队或大型代码库合作时，这是一个非常重要的奖励，但许多公司/程序员只是没有意识到他们一直缺少什么，在黑暗时代敲打他们（无证）的岩石： - ）

Answer 5

可能值得向老板询问他是否有任何已经记录的代码示例，以便您可以直接看到他所追求的内容。

Mark Needham撰写了一些关于阅读/记录代码的博客文章（参见Archive for the ‘Reading Code’ Category。

我记得前一段时间阅读Reading Code: Rhino Mocks，其中讨论的是如何绘制代码图，以帮助跟踪您的位置并“绘制”正在发生的事情。

希望有所帮助 - 祝你好运！

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

5 个答案: