.net - 代码文档: How much is too much?

Question

.NET源代码中有多少代码文档太多？

背景知识:我继承了一个大型代码库，该代码库是我在SO上发布的其他一些问题中谈到的。该代码库的“功能”之一是God类，它是一个静态类，具有超过3000行代码，包含数十种静态方法。从Utilities.CalculateFYBasedOnMonth()到Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6()的所有内容。 doesn't need to be rewritten只是重构成适当的库集，所有这些都是很好的代码。我已经计划好了。

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

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

这些示例是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;
        }

和:

    /// <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

我认为这里的问题很大一部分是MS强制我们使用的冗长而笨拙的XML文档语法(JavaDoc也不是更好)。如何格式化它的问题在很大程度上与适当的大小无关。

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

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

对我来说，它需要自然语言文档来描述函数的用途以及函数的任何前提条件和条件，参数以及返回值，这些条件无法通过编程语言语法来表示。