5

多くの要素が他の要素から継承される複雑なクラス構造があるとします。インターフェイスで定義されたメソッドがありGetStuff(string stuffName, int count)、それが他のインターフェイスに継承され、抽象クラスによって抽象的に実装され、具体的なクラスで明示的に実装されるなど...

GetStuff()Doxygen や Sandcastle などのツールで使用される XML コメントでコードを文書化する場合など、継承されたメンバーをどのように処理すればよいですか? 各レベルで同じ説明をコピーして貼り付けるのは間違っているようです。インターフェイス レベルと具象クラス レベルで異なる対象者を検討する必要がありますか? たとえば、インターフェイスの GetStuff() のドキュメントでは、インターフェイスを実装する人を考慮する場合がありますが、具象レベルのドキュメントでは、代わりにクラスを使用する人を考慮する場合がありますか?

4

2 に答える 2

5

  • コード コントラクトに従ってインターフェイス メソッドを文書化します。その実装についてはコメントしないでください。意味上の目的、つまり、どのようにではなく、何を行うべきかについてのみコメントしてください。このドキュメントの対象者は、実装者とユーザーの両方です。メソッドは実装されるだけでなく、呼び出されます。

  • インターフェースメソッドを実装していると言ってリンクするだけで、抽象メソッドを文書化します。これについては何も言う必要はありません。また、コメントを複製することは DRY (Don't Repeat Yourself) の原則に違反します。両方の場所で変更を加えることを覚えておく必要があります。(もちろん、インターフェイス メソッドを実装しない抽象メソッドの場合は、インターフェイス メソッドをドキュメント化するのと同じ方法でドキュメント化します。)

  • 具体的な実装は、インターフェイス メソッドを実装すること、および/または抽象メンバーをオーバーライドすることによって文書化します。必要に応じて、呼び出し元に関連する場合は、実装に関する情報を追加します。たとえば、パフォーマンス特性、スローされる可能性のある状況などです。

于 2010-08-21T03:38:20.547 に答える
2

EricAnastas による投稿の一部についてのコメント

各レベルで同じ説明をコピーして貼り付けるのは間違っているようです。

ただコピーするのは間違っていると想像できます。ただし、doxygenにコピーさせてから、その実装/スコープで変更したいものを変更することは可能です。詳細については、@copydocの説明を参照してください。

于 2011-06-12T02:07:28.087 に答える