スローされた例外をc＃/。netに文書化する方法

現在、社内の他の開発者が内部で使用する小さなフレームワークを書いています。

適切なIntellisense情報を提供したいのですが、スローされた例外を文書化する方法がわかりません。

次の例では：

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException

    // also may throw DivideByZeroException
}

例外を文書化するためのマークアップは次のとおりです。

/// <exception cref="SomeException">when things go wrong.</exception>

私が理解していないのは、によって呼び出され たコードによってスローされた例外を文書化する方法MyMethod1()ですか？

• によってスローされた例外を文書化する必要があります MyMethod2()
• によってスローされた例外を文書化する必要がありますFile.Open()か？

起こり得る例外を文書化する最良の方法は何でしょうか？

呼び出す可能性のあるメソッド内の例外も含め、コードによってスローされる可能性のあるすべての例外を文書化する必要があります。

リストが少し大きくなった場合は、独自の例外タイプを作成することをお勧めします。メソッド内で遭遇する可能性のあるすべてのものをキャッチし、それらを例外にラップして、それをスローします。

この方法で実行するもう1つの場所は、メソッドがAPIの前面にある場合です。ファサードが複数のインターフェースを単一のインターフェースに単純化するように、APIは複数の例外を単一の例外に簡略化する必要があります。呼び出し元がコードを使いやすくします。

Andrewの懸念の一部に（コメントから）答えるために、3種類の例外があります。知らないもの、知っているもので何もできないもの、知っているもので何かできるものです。

知らない人は手放したい。高速で失敗するという主な理由は、データが破損する可能性がある状態に入るよりも、アプリがクラッシュするほうがよいことです。クラッシュは何が起こったのか、なぜ起こったのかを教えてくれるので、「あなたが知らないもの」のリストからその例外を取り除くのに役立つかもしれません。

あなたが知っていて何もできないものは、OutOfMemoryExceptionsのような例外です。極端なケースでは、このような例外を処理する必要があるかもしれませんが、かなり顕著な要件がない限り、それらを最初のカテゴリのように扱います。あなたが持っているこれらの例外を文書化しますか？オブジェクトを新規作成するすべてのメソッドについて、OOMをドキュメント化するのはかなり愚かなように見えます。

あなたが知っていて、何かできることは、あなたが文書化し、包むべきものです。

あなたは、いくつかのより多く見つけることができるここに例外処理に関するガイドラインを。

標準のxmlドキュメントを使用する必要があります。

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

この方法で行うことの価値は、発生する可能性のある既知の例外のドキュメントを提供していることです。このドキュメントは、Visual Studioを使用していて、予想される例外を後で（または他のユーザーに）通知できる場合は、インテリセンスで利用できます。

特定の例外タイプを指定する必要があります。これは、1つのタイプの例外を処理できる場合がある一方で、他のタイプは深刻な問題の結果であり、修正できないためです。

いくつかの優れたアドインを使用することで、ドキュメント作成プロセスを簡単にすることができます。その1つがGhostDocです。これは、XML-docコメントを生成するVisual Studio用の無料のアドインです。また、ReSharperを使用する場合は、ReSharper用の優れたAgent Johnson Pluginをご覧ください。これにより、スローされた例外のXMLコメントを生成するオプションが追加されます。

更新： R＃8ではAgen Johnsonを使用できないようですが、代わりにReSharperの例外としてチェックアウト...

ステップ1：GhostDocはXMLコメント（Ctrl-Shift-D）を生成しますが、ReSharperのAgent Johnsonプラグインは例外も文書化することを提案しています：

手順2：ReSharperのショートカットキー（Alt-Enter）を使用して、例外のドキュメントも追加します。

ステップ2 http://i41.tinypic.com/osdhm

それが役に立てば幸い:)

私が理解していることから、<exception>要素を使用する目的は、例外ではなく、メソッドを装飾するときに使用することです。

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

呼び出された他のメソッドによってスローされる可能性がある例外は、それらのメソッドでキャッチ、処理、および文書化する必要があります。.NETによってスローされる可能性のある例外、または独自のコードによって明示的にスローされる例外を文書化する必要があります。

それより具体的になる限り、おそらく独自のカスタマイズされた例外をキャッチしてスローできますか？

メソッドの契約の一部は、前提条件が有効であることを確認することです。そのため、次のようにします。

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

なる

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo( somepath );
    if( !fi.Exists )
    {
        throw new FileNotFoundException("somepath doesn't exists")
    }
    // Maybe go on to check you have permissions to read from it.

    System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

このアプローチを使用すると、明示的にスローするすべての例外をドキュメント化する方が簡単です。スローされるOutOfMemoryException 可能性があることをドキュメント化する必要もありません。

メソッドによってスローされる可能性のあるすべての例外を文書化する必要があります。

実装の詳細を隠すために、私はMyMethod2からのいくつかの例外を自分で処理しようとします。

例外を処理または解決できない場合は、それらの更新を検討できます。主に、呼び出し元にとってより意味のある例外にパッケージ化/ラップされています。

実際、すでに回答されているため、例外を文書化する方法はXMLコメントを使用することです。

プラグインに加えて、TFSと統合できる静的分析ツールを使用して、例外が文書化されていることを確認することもできます。

以下のリンクでは、StyleCopのカスタムルールを作成して、メソッドによってスローされた例外がドキュメント化されていることを検証する方法を確認できます。

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -コメント-例外-II.aspx

よろしく。

メソッドで予期される例外を文書化します。例では、そのメソッドがファイルが見つからないという例外をスローする可能性があることをユーザーに通知します。

これは、発信者に何を期待するかを通知して、対処方法を選択できるようにすることを忘れないでください。