【发布时间】：2010-09-22 05:52:08
【问题描述】：
您的 .NET 源代码中有多少代码文档太多了？
一些背景知识：我继承了我在 SO 上发布的其他一些问题中谈到的大型代码库。该代码库的“特性”之一是 God Class，它是一个具有超过 3000 行代码的单个静态类，包含几十个静态方法。从Utilities.CalculateFYBasedOnMonth() 到Utilities.GetSharePointUserInfo() 再到Utilities.IsUserIE6() 无所不包。 doesn't need to be rewritten 的所有代码都很好，只是重构为一组适当的库。我已经计划好了。
由于这些方法正在进入一个新的业务层，而我在这个项目中的职责是准备系统以供其他开发人员维护，我正在考虑可靠的代码文档。尽管这些方法都具有良好的内联 cmets，但它们并不都具有 XML cmets 形式的良好（或任何）代码 doco。使用 GhostDoc 和 Sandcastle（或 Document X）的组合，我可以创建一些非常漂亮的 HTML 文档并将其发布到 SharePoint，这将使开发人员无需浏览代码本身就可以更多地了解代码的作用。
随着代码中文档数量的增加，导航代码变得越困难。我开始怀疑 XML cmets 是否会使代码更难维护，比方说，在每个方法上使用更简单的//comment。
这些例子是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, "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 cmets 记录所有代码，目的是使用 NDoc (RIP) 或 Sandcastle 之类的东西？如果没有，您如何决定哪些获取文档，哪些不获取？像 API 之类的东西显然会有 doco，但是你要交给另一个团队来维护的代码库呢？
你觉得我应该怎么做？
【问题讨论】：
-
这篇文章的赞成/反对过山车令人着迷。
标签： .net sandcastle xml-comments code-documentation ndoc