web-dev-qa-db-ja.com

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

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

良いインテリセンス情報を提供したいのですが、スローされた例外を文書化する方法がわからないhow.

次の例では：

_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()によってスローされた例外を文書化する必要がありますか？

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

c#.netdocumentationintellisense
135
Arnold Zokas

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

リストが少し大きくなる場合は、独自の例外タイプを作成できます。メソッド内で発生する可能性のあるものをすべてキャッチし、例外でラップしてスローします。

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

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

あなたが知らないものは手放したいです。これは高速で失敗するという原則です。つまり、データが破損する可能性のある状態になるよりも、アプリをクラッシュさせる方が適切です。クラッシュにより、何が起こったのか、なぜ起こったのかがわかります。これにより、その例外を「知らない人」リストから除外することができます。

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

知っていて何かできることは、文書化してラッピングするべきものです。

さらにいくつか見つけることができます 例外処理のガイドラインはこちら

106
Will

標準の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つのタイプの例外を処理できる場合がありますが、他のタイプは重大な問題の結果であり、修正できないためです。

91
chills42

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

更新：Agen JohnsonはR＃8、チェックアウトでは利用できないようです ReSharperの例外 代替手段として...

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

step 1

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

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

それが役立つことを願っています:)

34
Igal Tabachnik

私が理解したことから、<exception>要素を使用する意図は、例外ではなくメソッドを装飾するときにそれを使用することです：

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

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

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

10
Daniel Schaffer

メソッドの契約の一部として、前提条件が有効であることを確認する必要があります。

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
}

このアプローチを使用すると、OutOfMemoryExceptionmightがスローされることなどを文書化する必要なく、明示的にスローするすべての例外を文書化するのが簡単になります。

4
Rowland Shaw

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

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

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

1
GvS

実際、既に回答されているように、例外を文書化する方法はXMLコメントを使用しています。

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

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

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspxhttp://www.josefcobonnin.com/ post/2009/01/15/Xml-Documentation-Comments-Exceptions-II.aspx

よろしく。

1
Jose

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

対処方法を選択できるように、発信者に何を期待するかを通知することです。

0
Damien