.net – 代码文档：多少钱？

.NET源代码中的代码文档多少？

一些背景：我继承了我在这里发布的其他一些问题中谈到的大型代码库.该代码库的“功能”之一是God Class,一个具有> 3000行代码的单个静态类,包含几十个静态方法.这是从Utilities.CalculateFYBasedOnMonth()到Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6()的一切.这是所有好的代码,doesn’t need to be rewritten,只是重构了一套适当的图书馆.我有计划.

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

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

这些例子是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,"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,但是你要交给另一个团队维护的代码如何？

你觉得我应该怎么做？

我认为这里的很大一部分是MS已经强加于我们的详细和最重要的XML文档语法(JavaDoc也不是很好).如何格式化它的问题在很大程度上是独立于多少是适当的.

使用XML格式进行注释是可选的.您可以使用DOxygen或其他识别不同格式的工具.或者写自己的文档提取器 – 它不像你想的那样努力做一个合理的工作,是一个很好的学习经验.

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

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

.net – 代码文档：多少钱？

相关推荐