.NET 源代码中有多少代码文档过多？
一些背景：我继承了一个大型代码库，我在我在这里发布的一些其他问题中讨论过该代码库。该代码库的“功能”之一是 God Class，它是一个静态类，包含超过 3000 行代码，包含几十个静态方法。一切都是从Utilities.CalculateFYBasedOnMonth() to Utilities.GetSharePointUserInfo() to Utilities.IsUserIE6()。这都是很好的代码不需要重写，只是重构为一组适当的库。我已经计划好了。
由于这些方法正在进入新的业务层，而我在这个项目中的角色是为其他开发人员维护系统做好准备，因此我正在考虑可靠的代码文档。虽然这些方法都有良好的内联注释，但它们并不都具有 XML 注释形式的良好（或任何）代码 doco。使用 GhostDoc 和 Sandcastle（或 Document X）的组合，我可以创建一些非常漂亮的 HTML 文档并将其发布到 SharePoint，这将使开发人员更多地了解代码的用途，而无需浏览代码本身。
随着代码中文档数量的增加，浏览代码变得更加困难。我开始怀疑 XML 注释是否会使代码比更简单的代码更难维护//comment会在每个方法上。
这些例子是来自文档 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;
}
And:
/// <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;
}
}
所以我想知道你：你有记录吗all带有 XML 注释的代码，目的是使用 NDoc (RIP) 或 Sandcastle 之类的东西？如果没有，您如何决定哪些内容可以获取文档，哪些内容不能？像 API 这样的东西显然会有 doco，但是如果你要移交给另一个团队来维护的代码库呢？
你觉得我应该怎么做？
