9

クラスとインターフェイスを文書化する際のベスト プラクティスは何ですか。IFoo というインターフェイスから派生する Foo という具象クラスがあるとします。メソッドについてのコメントはどこに置きますか? インターフェイスと具体的なクラスに関するコメントを複製しますか?

コメントが重複している例を次に示します。

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}
4

9 に答える 9

19

私は両方にコメントを入れます。

インターフェイスについては、インターフェイス メンバーの背後にある意図と使用法についてコメントします。

実装については、特定の実装の理由についてコメントします。

于 2009-12-09T17:23:39.613 に答える
4

私は通常、両方に付けますが、同じことを言っているわけではありません。インターフェイスのコメントは、このメソッド/インターフェイスの抽象的な目的を説明する必要があります。具体的なコメントは、インターフェイスの目的のコンテキストでメソッド/クラスの実装の詳細について話します。

于 2009-12-09T17:20:47.200 に答える
4

私はそれらを両方に入れましたが、同期を維持するのは面倒で、疑わしい場合はインターフェイスにのみ入れました。

ほとんどの場合、インターフェイスを使用する必要があるコードを使用するときにツールチップが好きなので、これを行います...

于 2009-12-09T17:21:34.577 に答える
3

サンプルコードは、明示的なインターフェイス実装を使用していません。コードのクライアントは、クラスオブジェクトまたはインターフェイス参照のいずれかを介してメソッドを呼び出すことができるため、両方が必要になります。明示的なインターフェイスの実装では、クライアントがそれを見ることができないため、クラスメソッドのコメントを省略できます。これは、XMLドキュメントを使用してIntelliSense情報を生成していることを前提としています。

于 2009-12-09T17:29:03.350 に答える
2

両方ですが、同期を維持する機能が組み込まれていることを望みます

于 2009-12-09T17:25:11.707 に答える
2

<referTo>System. .... </referTo>コメントをリンクするタグが理想的です

于 2009-12-09T17:46:52.910 に答える
2

理想的には、すべての具体的な実装が満たす必要があるコントラクトを定義するため、インターフェースのみを文書化する必要があります。

于 2009-12-09T17:50:01.053 に答える
2

インターフェイスのみ。この場合、それらを同期する必要がないからです。私の IDE は、具象クラスのインターフェイス コメントを確認するのに役立ちます。API ドキュメント ジェネレーターも同じことを行います。

于 2009-12-09T17:24:25.837 に答える
1

私は本当にそれらをまったく使用しません。代わりに、コードを構造化し、すべてのメソッドと変数にコメントなしで何をするかが明確になるように名前を付けます。コメントの問題は、コメントがコンパイルも実行もされず、単体テストによってテストされないことです。そのため、コメントをコードと同期させることはほとんど不可能です。

于 2009-12-09T17:24:14.557 に答える