相关疑难解决方法(0)

您的.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 …