5

私はXML コメントが大好きです。ただし、すべてを折りたたむと、2 行ごとに次のようになります。

[/// summary ...]
public void CreateUser(string username, string password)[...]

これに数十または数百のメソッドを掛けると、結果の折りたたまれたコードをふるいにかけるのは困難です。 これらのコメントを別の XML ファイルに移動しても、Visual Studio に関連付けを認識させて、Intellisense に表示されるようにすることはできますか? もしそうなら、どうすればその関連付けを行うことができますか？また、これらのコメントに基づいてドキュメントを生成するために SandCastle も使用しているため、関連付けは SandCastle によっても認識される必要があります。

4

3 に答える 3

7

タグを使用して、<include file='...' path='...'>外部コメントを参照できます。http://msdn.microsoft.com/en-us/library/9h8dy30z.aspxを参照してください。

既存のソースファイルのコメントを外部のコメントファイルに移動するツールを知りません。

于 2012-07-18T03:43:40.533 に答える
0

短い答え：AFAIK No.

XML コメントは、サード パーティによって使用される公に公開されたメソッドに役立ちます。私がアプリケーションに追加するほぼすべての公開機能は、コントラクト インターフェースを介して行われるため (テスト機能を支援するため)、インターフェース宣言に対してコメントを挿入し、その上に <see cref="..."/> を使用します。実装。

インターフェース：

///<summary>
/// Provides so-in-so fetching functionality on the provided criteria.
/// Examples, parameters, etc.
///</summary>
IEnumarable<Something> FetchSomethingsBaseOnCriteria(params Criteria[] criteria);

実装

///<summary>
/// <see cref="ISomethingDoer.FetchSomethingsBasedOnCriteria"/>
///</summary>
IEnumarable<Something> ISomethingDoer.FetchSomethingsBaseOnCriteria(params Criteria[] criteria)
{
  // Get fetching...
}

ほとんどのドキュメント ジェネレーターが <see/> からのコメントを解決するスマートさを持っているかどうかはわかりませんが、Sandcastle には <Inheritdoc/> タグがあり、ベース インターフェイスのコメントを取得できるようになっていると思います。http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

ポリモーフィック インターフェイスを使用している場合、これは機能しない場合があります。（中間インターフェースで宣言/コメントをオーバーライドできるとは思わない）

内部使用およびプライベート コードについては、コメントを気にしません。あまりにも簡単に同期が外れてしまうと、ユーザーを誤解させたり、無視したりする必要があります。(「コメントは嘘です。」 - クリーン コード) 私は、BDD スタイルの単体テストを使用して、コードで実行する意図を記述し、記述コードを使用してそれ自体を記述します。

于 2012-07-18T03:05:11.340 に答える