代码文档：多少太多？ [英] Code documentation: How much is too much?

问题描述

.NET源代码中的代码文档太多了？

How much code documentation in your .NET source is too much?

某些背景：我继承了一个大型代码库，在其他一些代码中我已经谈到我在此处发布的问题。该代码库的功能之一是God类，它是一个静态类，具有超过3000行代码，包含数十种静态方法。从 Utilities.CalculateFYBasedOnMonth（）到 Utilities.GetSharePointUserInfo（）到 Utilities.IsUserIE6 （）。都是很好的代码，不需要重写，只需将其重构为适当的库集。我已经计划好了。

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.

由于这些方法正在进入新的业务层，而我在该项目中的角色是为其他开发人员准备维护系统，正在考虑扎实的代码文档。尽管这些方法都具有良好的内联注释，但它们均不具有XML注释形式的良好（或任何）代码文件。使用GhostDoc和Sandcastle（或Document X）的组合，我可以创建一些非常漂亮的HTML文档并将其发布到SharePoint，这将使开发人员无需浏览代码本身就可以更多地了解代码的作用。

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.

随着代码中文档数量的增加，导航代码变得更加困难。我开始怀疑XML注释是否会使代码的维护比每种方法上更简单的 // comment 难。

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.

这些示例是文档中的 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的功能，但是要交给另一个团队维护的代码库呢？

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?

推荐答案

我认为问题的很大一部分是MS对我们施加的冗长而笨拙的XML文档语法（JavaDoc也不是更好）。在很大程度上，如何设置格式的问题与合适的格式无关。

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.

使用XML格式的注释是可选的。您可以使用DOxygen或其他识别不同格式的工具。或编写自己的文档提取器-做到合理的工作并不难，并且是一种很好的学习体验。

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.

多少钱的问题比较困难。如果您要维护一些代码，我认为自记录代码的想法很好。如果您只是客户，则无需阅读代码即可了解给定功能的工作原理。当然，很多信息隐含在数据类型和名称中，但是有很多不是。例如，传递对对象的引用可以告诉您所期望的内容，但不能告诉您如何处理空引用。或在OP的代码中，如何处理参数开头或结尾的空格。我认为应该记录的这类信息比通常公认的要多。

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.

这篇关于代码文档：多少太多？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！