インターフェイスとその実装の文書化[終了]

Question

HTMLヘルプファイルを作成できるように、コメントでC＃コードを装飾しています。

インターフェイスを宣言して文書化することがよくあります。ただし、これらのインターフェイスを実装するクラスは、実装に応じて特定の例外をスローできます。

クライアントは、使用しているインターフェイスのみを認識する場合があります。実装者によってスローされる可能性のある例外を追加して、インターフェイスを文書化する必要がありますか？

インターフェース実装者がフレームワークの例外の代わりにこれらをスローするように、カスタム例外を作成/文書化する必要がありますか？

これが明確であることを願っています！

ありがとう

EDIT 2010年1月4日：この例外とカスタム例外に関するブログ投稿を http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

あなたの質問を完全に理解したかどうかはわかりません（私はJavaであり、C＃開発者ではありません）が、本質的にポリモーフィズムの問題について尋ねているようです：誰かがXとYをスローするように宣言されていますが、実装がZをスローするとどうなりますか？

従うべきことの1つは、本質的にサブタイプがスーパータイプの動作に準拠する必要があることを示す準拠の原則です。つまり、インターフェイス内のメソッドが1つのタイプの例外（たとえば、nullポインター例外）のみをスローできることを文書化する場合、呼び出し元との契約は、これが唯一の注意すべきことであるということです。他の何かを投げると、驚くかもしれません。

スーパータイプ内の特定のサブタイプに関することを文書化することは、不要な結合を作成するため、良いアイデアではありません。実装が宣言とは異なる動作をする可能性があるという事実は、宣言が十分に肉付けされていないことを示唆する可能性があるため、より懸念されます。

メソッドがスローする可能性のあるすべての例外タイプを考えてみてください。それらのスーパータイプを作成し、インターフェイスメソッドで明示的に宣言します（たとえば、このメソッドは「計算例外」をスローできます）。次に、実装で、詳細を含む計算例外をスローするか、実装に固有の計算例外のサブタイプをスローしますが、それでも準拠します。

Answer 2

U >

しかし、あなたのエラー状態を説明する既存の.Net Framework例外がある場合、それを使用する必要はありません

実装者向けの文書化に関しては、コメントの注釈セクションを使用して（XMLコメントを使用していると仮定して）、実装者に期待される方法などを説明できます。明らかにこれは強制力のある方法ではありませんが、開発者がAPIを使用するようになったときに有用なガイドラインとして役立ちます