.NET ソース内のコード ドキュメントの量が多すぎますか?
いくつかの背景: SO に投稿した他の質問のいくつかで話した大きなコードベースを継承しました。このコードベースの「機能」の 1 つは、God クラスです。これは、数十の静的メソッドを含む 3000 行を超えるコードを持つ単一の静的クラスです。Utilities.CalculateFYBasedOnMonth()からまでのすべてUtilities.GetSharePointUserInfo()ですUtilities.IsUserIE6()。適切なライブラリ セットにリファクタリングするだけで、書き換える必要のない優れたコードです。私はそれを計画しています。
これらのメソッドは新しいビジネス レイヤーに移行しており、このプロジェクトでの私の役割は、他の開発者がシステムを保守できるように準備することなので、しっかりしたコード ドキュメントについて考えています。これらのメソッドにはすべて適切なインライン コメントがありますが、XML コメント形式の適切な (またはまったく) コード doco がすべて含まれているわけではありません。GhostDoc と Sandcastle (または Document X) の組み合わせを使用して、非常に優れた HTML ドキュメントを作成し、それを SharePoint に投稿できます。これにより、開発者は、コード自体をナビゲートしなくても、コードが何をするかをより理解できるようになります。
コード内のドキュメントの量が増えると、コードをナビゲートするのが難しくなります。//commentXML コメントを使用すると、たとえば、各メソッドを単純にするよりも、コードの保守が難しくなるのではないかと考え始めています。
これらの例は、ドキュメント 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;
}
}
だから私はあなたから疑問に思っていました: NDoc (RIP) や Sandcastle のようなものを使用することを目標に、すべてのコードを XML コメントで文書化していますか? そうでない場合、ドキュメントを取得するものと取得しないものをどのように決定しますか? API のようなものには明らかに doco がありますが、別のチームに引き渡して維持するコードベースについてはどうでしょうか?
私は何をすべきだと思いますか？