一些背景：我继承了我在这里发布的其他一些问题中谈到的大型代码库.该代码库的“功能”之一是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,但是你要交给另一个团队维护的代码如何？

你觉得我应该怎么做？