150

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

適切な 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()ますか?

考えられる例外を文書化する最良の方法は何ですか?

4

8 に答える 8

115

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

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

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

アンドリューの懸念のいくつかに答えるために (コメントから)、3 つのタイプの例外があります: あなたが知らないもの、あなたが知っていて何もできないもの、あなたが知っていて何かをすることができるものです。

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

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

あなたが知っていて、何かをすることができるものは、文書化してラップする必要があります。

例外処理に関するその他のガイドラインについては、こちらを参照してください。

于 2009-01-20T13:51:29.567 に答える
106

標準の 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 を使用している場合は、このドキュメントを IntelliSense で利用でき、後で予想される例外について自分 (または他の人) に思い出させることができます。

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

于 2009-01-20T13:46:28.263 に答える
36

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

更新: Agen Johnson は R# 8 では利用できないようです。代替手段としてReSharper の例外をチェックしてください...

ステップ 1: GhostDoc は XML コメント (Ctrl-Shift-D) を生成しますが、ReSharper のエージェント ジョンソン プラグインは例外の文書化も提案します。

ステップ1

ステップ 2: ReSharper のショートカット キー (Alt-Enter) を使用して、例外ドキュメントも追加します。

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

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

于 2009-01-20T14:28:11.550 に答える
12

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

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

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

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

于 2009-01-20T13:44:49.500 に答える
4

メソッドのコントラクトの一部は、前提条件が有効であることを確認することです。したがって、次のようになります。

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 可能性があることなどを文書化する必要なしに、明示的にスローするすべての例外を文書化する方が簡単です。

于 2009-01-20T14:10:29.323 に答える
1

実際、すでに回答されているように、例外を文書化する方法は 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

よろしく。

于 2009-04-29T09:29:44.317 に答える
1

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

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

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

于 2009-01-20T13:43:51.390 に答える
0

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

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

于 2009-01-20T13:44:18.050 に答える