您的 .NET 源代码中有多少代码文档太多了？
一些背景：我继承了我在 SO 上发布的其他一些问题中谈到的大型代码库。该代码库的“特性”之一是 God Class，它是一个具有超过 3000 行代码的单个静态类，包含几十个静态方法。这是从Utilities.CalculateFYBasedOnMonth()到Utilities.GetSharePointUserInfo()到的一切Utilities.IsUserIE6()。这都是不需要重写的好代码，只需重构为一组适当的库。我已经计划好了。
由于这些方法正在进入一个新的业务层，而我在这个项目中的角色是准备系统以供其他开发人员维护，我正在考虑可靠的代码文档。尽管这些方法都具有良好的内联注释，但它们并不都具有 XML 注释形式的良好（或任何）代码文档。使用 GhostDoc 和 Sandcastle（或 Document 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，但是你要交给另一个团队来维护的代码库呢？
你觉得我应该怎么做？