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

StackOverflow https://stackoverflow.com/questions/461306

質問

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

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

次の例：

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()によってスローされた例外を文書化すべきですか？

可能な例外を文書化する最良の方法は何ですか？

役に立ちましたか？

解決

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

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

メソッドをAPIの表面に配置する場合は、この方法でこれを行うことができます。ファサードが複数のインターフェースを単一のインターフェースに単純化するように、APIは複数の例外を単一の例外に単純化する必要があります。呼び出し元がコードを簡単に使用できるようにします。

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

自分のことを知らない人は手放したい。これは、高速で失敗することの原則です。つまり、データが破損する可能性のある状態になるよりも、アプリをクラッシュさせる方が適切です。クラッシュは、何が起こったのか、なぜ起こったのかを教えてくれるので、その例外を<！> quot;あなたが知らない<！> quot;リスト。

あなたが知っていて何もできないのは、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のエージェントジョンソンプラグイン。これにより、スローされた例外のXMLコメントを生成するオプションが追加されます。

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

  

ステップ1：GhostDocがXMLを生成します   コメント（Ctrl-Shift-D）、エージェントジョンソンプラグイン   ReSharperは、   例外も：

ステップ1

  

ステップ2：ReSharperのショートカットキーを使用する   （Alt-Enter）例外を追加する   ドキュメントも：

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

役立つ希望：）

私が理解していることから、<！> lt; exception <！> gt;を使用する意図要素は、例外ではなくメソッドを装飾するときに使用します：

/// <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 might がスローされることなどを文書化する必要なく、明示的にスローするすべての例外を文書化する方が簡単です。

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

実装の詳細を隠すために、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-Comments-Exceptions-II.aspx

よろしく。

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

呼び出し元に何を期待するかを通知し、対処方法を選択できることを忘れないでください。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top