代码文档：多少算太多？
.NET 源代码中有多少代码文档过多？
一些背景：我继承了一个大型代码库，我在我在这里发布的一些其他问题中讨论过该代码库。 该代码库的“功能”之一是 God Class，它是一个静态类，包含超过 3000 行代码，包含几十个静态方法。 从 Utilities.CalculateFYBasedOnMonth() 到 Utilities.GetSharePointUserInfo() 到 Utilities.IsUserIE6()，应有尽有。 这些都是很好的代码，不需要重写，只需重构为适当的库集。 我已经计划好了。
由于这些方法正在进入新的业务层，而我在这个项目中的角色是为其他开发人员维护系统做好准备，因此我正在考虑可靠的代码文档。 虽然这些方法都有良好的内联注释，但它们并不都具有 XML 注释形式的良好（或任何）代码 doco。 使用 GhostDoc 和 Sandcastle（或 Document X）的组合，我可以创建一些非常漂亮的 HTML 文档并将其发布到 SharePoint，这将使开发人员更多地了解代码的用途，而无需浏览代码本身。
随着代码中文档数量的增加，浏览代码变得更加困难。 我开始怀疑 XML 注释是否会比每个方法上更简单的 //comment 更难维护代码。
这些示例来自文档 X 示例：
/// <summary>
/// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
/// </summary>
/// <returns>A new Customer instance that represents the new customer.</returns>
/// <example>
/// The following example demonstrates adding a new customer to the customers
/// collection.
/// <code lang="CS" title="Example">
/// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
/// </code>
/// <code lang="VB" title="Example">
/// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
/// </code>
/// </example>
/// <seealso cref="Remove">Remove Method</seealso>
/// <param name="Title">The customers title.</param>
/// <param name="FirstName">The customers first name.</param>
/// <param name="MiddleInitial">The customers middle initial.</param>
/// <param name="LastName">The customers last name.</param>
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
{
// create new customer instance
Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);
// add to internal collection
mItems.Add(newCust);
// return ref to new customer instance
return newCust;
}
并且：
/// <summary>
/// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
/// </summary>
/// <value>
/// An Int value that specifies the number of Customer instances within the
/// collection.
/// </value>
public int Count
{
get
{
return mItems.Count;
}
}
所以我想知道您的意见：您是否使用 XML 注释来记录所有代码，目的是使用 NDoc (RIP) 或 Sandcastle 之类的东西？ 如果没有，您如何决定哪些内容可以获取文档，哪些内容不能？ 像 API 这样的东西显然会有 doco，但是你要移交给另一个团队来维护的代码库又如何呢？
你觉得我应该怎么做？
How much code documentation in your .NET source is too much?
Some background: I inherited a large codebase that I've talked about in some of the other questions I've posted here on SO. One of the "features" of this codebase is a God Class, a single static class with >3000 lines of code encompassing several dozen static methods. It's everything from Utilities.CalculateFYBasedOnMonth() to Utilities.GetSharePointUserInfo() to Utilities.IsUserIE6(). It's all good code that doesn't need to be rewritten, just refactored into an appropriate set of libraries. I have that planned out.
Since these methods are moving into a new business layer, and my role on this project is to prepare the system for maintenance by other developers, I'm thinking about solid code documentation. While these methods all have good inline comments, they don't all have good (or any) code doco in the form of XML comments. Using a combo of GhostDoc and Sandcastle (or Document X), I can create some pretty nice HTML documentation and post it to SharePoint, which would let developers understand more about what the code does without navigating through the code itself.
As the amount of documentation in the code increases, the more difficult it becomes to navigate the code. I'm beginning to wonder if the XML comments will make the code more difficult to maintain than, say, a simpler //comment would on each method.
These examples are from the Document X sample:
/// <summary>
/// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
/// </summary>
/// <returns>A new Customer instance that represents the new customer.</returns>
/// <example>
/// The following example demonstrates adding a new customer to the customers
/// collection.
/// <code lang="CS" title="Example">
/// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
/// </code>
/// <code lang="VB" title="Example">
/// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
/// </code>
/// </example>
/// <seealso cref="Remove">Remove Method</seealso>
/// <param name="Title">The customers title.</param>
/// <param name="FirstName">The customers first name.</param>
/// <param name="MiddleInitial">The customers middle initial.</param>
/// <param name="LastName">The customers last name.</param>
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
{
// create new customer instance
Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);
// add to internal collection
mItems.Add(newCust);
// return ref to new customer instance
return newCust;
}
And:
/// <summary>
/// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
/// </summary>
/// <value>
/// An Int value that specifies the number of Customer instances within the
/// collection.
/// </value>
public int Count
{
get
{
return mItems.Count;
}
}
So I was wondering from you: do you document all of your code with XML comments with the goal of using something like NDoc (RIP) or Sandcastle? If not, how do you decide what gets documentation and what doesn't? Something like an API would obviously have doco, but what about a codebase that you're going to hand off to another team to maintain?
What do you think I should do?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（14）
没有人提到您的代码不需要臃肿，XML 文档可以位于另一个文件中：
然后您的 Add 方法可以在其上方不包含额外的 XML/注释，或者如果您只喜欢摘要（因为它与单独的摘要合并）文件）。
它比 Javadoc 和 PHP/Javascript 中的衍生格式等垃圾格式强大得多（尽管 Javadoc 为 XML 语法铺平了道路）。 另外，可用的工具要优越得多，并且帮助文档的默认外观更具可读性并且更易于自定义（我可以说，通过编写 doclet 并将该过程与 Sandcastle/DocProject/NDoc 进行比较）。
Nobody's mentioned your code doesn't need to be bloated, the XML documentation can be in another file:
And then your Add method can contain no extra XML/comments above it, or if you prefer just the summary (as that's merged with the separate file).
It's far more powerful than the rubbish format that is Javadoc and derivatives you find in PHP/Javascript (though Javadoc paved the way for the XML syntax). Plus the tools available are far superior and the default look of the help docs is more readable and easier to customise (I can say that from having written doclets and comparing that process to Sandcastle/DocProject/NDoc).
我认为这里的问题很大一部分是 MS 强加给我们的冗长且粗俗的 XML 文档语法（JavaDoc 也好不到哪儿去）。 在很大程度上，如何格式化它的问题与多少合适无关。
使用 XML 格式进行注释是可选的。 您可以使用 DOxygen 或其他识别不同格式的工具。 或者编写您自己的文档提取器 - 完成合理的工作并不像您想象的那么难，并且是一次很好的学习经历。
多少的问题更困难。 我认为如果您正在深入维护一些代码，那么自记录代码的想法很好。 如果您只是客户，则不需要阅读代码来了解给定函数的工作原理。 当然，许多信息都隐含在数据类型和名称中，但也有很多信息不是隐含的。 例如，传入对象的引用会告诉您预期的结果，但不会告诉您如何处理空引用。 或者在OP的代码中，如何处理参数开头或结尾的任何空格。 我相信应该记录的此类信息远多于通常所认识的信息。
对我来说，它需要自然语言文档来描述函数的用途以及函数的任何前置条件和后置条件、其参数和返回值，这些不能通过编程语言语法来表达。
I think a good part of the problem here is the verbose and crufty XML documentation syntax MS has foisted on us (JavaDoc wasn't much better either). The question of how to format it is, to a large degree, independent of how much is appropriate.
Using the XML format for comments is optional. You can use DOxygen or other tools that recognize different formats. Or write your own document extractor -- it isn't as hard as you might think to do a reasonable job and is a good learning experience.
The question of how much is more difficult. I think the idea of self-documenting code is fine, if you are digging in to maintain some code. If you are just a client, you shouldn't need to read the code to understand how a given function works. Lots of information is implicit in the data types and names, of course, but there is a great deal that is not. For instance, passing in a reference to an object tells you what is expected, but not how a null reference will be handled. Or in the OP's code, how any whitespace at the beginning or the end of the arguments are handled. I believe there is far more of this type of information that ought to be documented than is usually recognized.
To me it requires natural language documentation to describe the purpose of the function as well as any pre- and post-conditions for the function, its arguments, and return values which cannot be expressed through the programming language syntax.
您在维护新库的人和使用新库的人之间遇到了关键的分歧。
如果我正在编写一个新的应用程序并将使用这些标准库，我应该获得这些库的稳定二进制文件，然后将它们简单地导入到我的应用程序中，而不是从某个位置复制源代码，并且如果代码可能会导致问题被修改。 在这种情况下，除了方法名称和输入/输出参数之外，我将无法访问任何“自记录”功能，如果我使用某种 IDE，即使这些功能也不会公开没有打开自动完成功能。
所以在上面的示例代码中，我认为它看起来很好。 代码本身并不太冗长，并且名称是自记录的。 另一方面，所有必要的摘要/参数数据都在那里，以便可以构建可靠的文档片段，使图书馆的使用者能够轻松获得所有关键信息。 遗憾的是 XML 相当臃肿，但总的来说，我认为大多数开发人员都可以轻松浏览所有摘要内容并查看方法中的实际代码。
You're hitting a critical divide here between those that will be maintaining the new libraries and those that will be consuming the new libraries.
If I'm writing a new application and will be using these standard libraries, I should be getting a stable binary of the libraries and simply importing them into my application, not copying the source code down from a location and potentially causing problems if the code gets modified. In that case, I won't have access to any of the "self documenting" features other than the name of the method and the input/output parameters, and even those won't be exposed if I'm using some kind of IDE that doesn't have the auto complete featured turned on.
So in your example code above, I think it looks just fine. Things are not too verbose within the code itself and the names are self documenting. On the flip side, all of the necessary summary/parameter data is there so that a solid documentation piece could be constructed to allow those consuming the library to have all the critical information at their fingertips. Sadly XML is rather bloated, but by in large I think most developers can easily browse right by all the summary content and look into the actual code within the method.
Jeff 有一篇关于评论（或者我应该说，不评论）的非常好的文章在这里...
http://www.codinghorror.com/blog/archives/001150.html
我知道我似乎没有回答这个问题，但我认为代码应该是自记录的，这是一个有效的观点尽可能。
Jeff has a really good article about commenting (or should I say, not commenting) here...
http://www.codinghorror.com/blog/archives/001150.html
I know it seems like I'm not answering the question, but I think it's a valid point that code should be as self-documenting as possible.
我倾向于在自己的代码中记录所有公共方法； 使用 GhostDoc 可以让这变得很简单。 为了减少编辑源代码时的混乱，我通常首先进入“大纲模式”（即使用 Visual Studio 的“大纲”>“折叠到定义”命令）来折叠注释。
我从未尝试过 Sandcastle，但我真的很感谢 Intellisense 为我的 XML 注释方法提供的便利。
I tend to document all public methods in my own code; using GhostDoc makes this trivial. And in order to reduce the clutter when I edit my source code, I generally just collapse the comments by going first into "outline mode" (i.e. use Visual Studio's Outline > Collapse to definitions command).
I've never tried Sandcastle, but I really appreciate the comfort provided by Intellisense for the methods I have XML-commented.
我总是选择 XML / Javadoc 格式的注释，因为我喜欢能够以合理的格式（通常是 HTML）浏览 API 文档。
它确实成为浏览实际源代码的问题，但我发现这通常是一个小问题，因为 Visual Studio 通常非常智能地根据需要折叠 XML 注释。
I always opt for the XML / Javadoc format comments, because I love being able to browse API documentation in a sensible format (HTML usually).
It does become a problem for browsing the actual source code, but I find that this is generally a minor issue, since Visual Studio is generally pretty smart about collapsing XML comments as necessary.
不要重复自己。
第一个方法的名称应该反映分配了一个新对象。
如果该行为在整个框架中对于每个添加都是标准的，则应该在更高级别上记录它，而不是在此方法 API 文档中。 否则，请更改名称。
评论应该添加信息，而不是将其隐藏在噪音中。 必要时在 XML 中应该有注释。 以及它们增加价值的地方。
我不想看到：
对于名为 count 的方法，“返回计数”。
Don't repeat yourself.
The name of the first method should reflect that a new object is allocated.
If that behavior is standard throughout the framework for each add, it should be documented on a higher level, not in this method API doc. Otherwise, change the name.
Comments should add information, not hide it in noise. And there should be comments, where necessary in XML. And where they add value.
I do not want to see:
"returns the count" for a method named count.
所有公共函数都必须能够被对您的代码库有一定了解的人清楚地理解，但在您的特定部分中则不需要深入研究代码。
如果您需要编写一小段代码来解释函数的作用，那么您的函数/类的命名很可能很糟糕。 在这种情况下，名称应该是不言自明的。
如果需要超过 1 个简短的句子来解释，这可能是一个很好的注释。
如果需要一个段落，则除了可能不清楚的名称之外，您的函数可能还做了太多事情。
如果您确保评论准确，通常最好避免评论。如果您确保评论准确。 不准确和/或无法维护的注释比没有注释更糟糕
因此应用这些规则：
在第一个示例中：“//创建新的客户实例”是多余的。 代码非常清晰。 其他评论都很完美。 他们澄清了代码的操作内容/结果是什么
在您的第二个示例中，注释是浪费精力并且难以阅读。 您所需要做的就是为该函数指定一个适当的名称。 不是那种模糊的“计数”。 这是糟糕的命名。
All public functions must be clearly understandable by someone who has a passing familiarity with your code base, but NOT in your specific section without having to delve into the code.
If you need to write a short line to explain what a function does, chances are you named your function/classes poorly. The name should be self explanatory in that case
If it requires more than 1 brief sentence to explain, that's probably a good comment
If it takes a paragraph, your function is probably doing too much besides likely unclear names.
It's usually better to err on the side of comments IF YOU MAKE SURE THEY ARE ACCURATE. Inaccurate and/or unmaintainable comments are worse than no comments
So applying these rules:
In your first example: "// create new customer instance" is redundant. The code is crystal clear. THe other comments are perfect. They clarify what the code is operating upon/what it's resuls are
In your second example the comments are wasted effort and make it hard to read. All you need to do is give the function a proper name. Not that vague "count". That is poor naming.
我最近进行的一项研究表明，如果您有重要的“指令”，例如，调用者必须在许多规范中执行 X（例如，“此方法执行 X，这意味着 Y 和 Z”），那么存在非常高的风险事实上，当你的读者看到很长的文档时，他们会跳过阅读它，
所以至少，将重要的内容分开或使用标签（问我是否使用 Java）。
I recently conducted a study that shows that if you have important "directives "e.g., Caller must do X" within a lot of specifications (e.g., "this method does X which means Y and Z"), there is a very high risk that your readers would miss the directives. In fact, when they see a long documentation, they skip reading it alltogether.
So at the least, separate the important stuff or use tagging (ask me if you use Java).
这完全取决于您公司使用的标准，但对于我的团队来说，我们在每个函数的顶部都进行了记录，就像您的第二个示例一样（顺便说一下，您可以在 Visual Studio 2008 中通过按“/”键 3 次来完成此操作在任何子或函数顶部的一行！！）。
第一个示例有点矫枉过正，尤其是底部几行，每行都带有注释。 然而，我认为函数头部的内容可能很有用，因为我们在这里经常使用它。 从我从许多其他程序员那里了解到的情况来看，它似乎有些标准。
It all depends on the standards your company is using, but for my crew, we document at the top of every function like in your second example (which by the way you can do in Visual Studio 2008 by hitting the "/" key 3 times in a row at the top of any sub or function!!).
The first example is overkill, especially the bottom couple of lines where each line is commented. However, I think the stuff at the header of the function might be useful though, because we use it here a lot. And it appears to be somewhat standard from what I can tell from lots of other programmers.
我见过建议不要对自我注释代码和方法重载进行注释的编码标准。 虽然 YMMV，这听起来像是摆脱“Field _numberOfCars 是一个代表汽车数量的整数”类型评论的好方法，这些评论会导致过度杀伤。
I've seen coding standards that recommend against commenting self-commenting code and method overloads. While YMMV, it sounds like a good way to get away from the "Field _numberOfCars is an integer that represents the number of cars"-type comments that lead into overkill.
用于生成文档的标题中的注释是一件好事。 在代码中添加注释来解释为什么要做你正在做的事情通常也是一件好事。 添加多余的注释来解释你所做的事情并不是一件好事
Comments in a header for generating documentation is a good thing. Putting comments in code to explain why you are doing what you are doing is also usually a good thing. Putting in redundant comments paraphrasing what you did is not a good thing
你所展示的太多了。 帮自己一个忙，删除它！
代码首先应该通过有意义的方法和参数名称进行自我记录。 在您展示的示例中；
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName) 完全可以理解正在发生的事情的意图，“Count”也是如此。
正如您所指出的，这样的评论纯粹是围绕易于阅读的代码的噪音。 大多数开发人员会更快地开放检查和使用代码，而不是堆砌晦涩的自动生成的 API 文档。 每次！
What you have shown is FAR TOO MUCH. Do your self a favour and delete it!
Code should first off be self documenting, through meaningful method and parameter names. In the example you have shown;
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName) is perfectly understandable to the intent of what is happening, as is 'Count'.
Commenting such as this, as you pointed out, is purely noise around what is otherwise easy to read code. Most developers will sooner open up examine and use the code, than pile through obscure auto-generated API documentation. Everytime!
顺便说一句，根据“干净的代码”（一本很棒的书，BTW），人们应该避免在嵌入源代码的注释中使用 HTML/XML 标记。 即使您的 IDE 在您将鼠标悬停时可以创建漂亮的文档，但当您仅浏览源代码时，它会被认为过于分散注意力且难以阅读。
By the way, according to "Clean code" (A great book, BTW), one should avoid using HTML/XML markups within comments that are embedded in the source code. Even if your IDE can create nifty documentation when you hover, it is considered too distracting and unreadable when you just browse your sources.