代码文档:多少钱太多了？

Question

您的.NET源代码文档中有多少是太多了？

一些背景:我继承了一个很大的代码库,我已经在SO上发布了一些其他问题.这个代码库的一个"特性"是God Class,一个包含大约3000行代码的单个静态类,包含几十个静态方法.这是一个从一切Utilities.CalculateFYBasedOnMonth()要Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6().这些都是不需要重写的好代码,只需重构成一组适当的库.我已经计划好了.

由于这些方法正在进入一个新的业务层,我在这个项目中的角色是为其他开发人员准备系统以进行维护,我正在考虑可靠的代码文档.虽然这些方法都具有良好的内联注释,但它们并不都具有XML注释形式的良好(或任何)代码doco.使用GhostDoc和Sandcastle(或文档X)的组合,我可以创建一些非常好的HTML文档并将其发布到SharePoint,这将使开发人员更多地了解代码的作用,而无需浏览代码本身.

随着代码中文档量的增加,导航代码变得越困难.我开始怀疑XML注释是否会使代码更难以维护,比如说//comment每个方法更简单.

这些示例来自Document 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,但是你要将代码库移交给另一个团队进行维护呢？

你觉得我应该怎么做？

Answer 1

没有人提到你的代码不需要膨胀,XML文档可以在另一个文件中:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

然后你的Add方法不能在它上面包含额外的XML /注释,或者你只是喜欢摘要(因为它与单独的文件合并).

它比Javadoc和你在PHP/Javascript中找到的衍生物的垃圾格式强大得多(尽管Javadoc为XML语法铺平了道路).此外,可用的工具要优越得多,帮助文档的默认外观更易读,也更容易定制(我可以说,从编写doclet并将该过程与Sandcastle/DocProject/NDoc进行比较).

Answer 2

我认为这里的问题很大一部分是MS强加给我们的冗长和苛刻的XML文档语法(JavaDoc也没有好多少).如何格式化它的问题在很大程度上取决于多少是合适的.

使用XML格式进行注释是可选的.您可以使用DOxygen或其他识别不同格式的工具.或者编写自己的文档提取器 - 这并不像你想象的那样难以做一份合理的工作并且是一种很好的学习体验.

问题是多少更难.我认为自编文档代码的想法很好,如果你正在挖掘维护一些代码.如果您只是一个客户端,则不需要阅读代码来了解给定函数的工作原理.当然,大量信息隐含在数据类型和名称中,但有很多信息并非如此.例如,传入对象的引用会告诉您预期的内容,但不会告诉您如何处理空引用.或者在OP的代码中,如何处理参数开头或结尾的任何空格.我认为应该记录的这类信息远远多于通常认可的信息.

对我而言,它需要自然语言文档来描述函数的目的以及函数的前置和后置条件,其参数和返回值,这些都不能通过编程语言语法表达.