13

XMLコメントをどこに適用すべきかに興味があります。より一般的なXMLコメントをインターフェースに配置し、より説明的なコメントを実装クラスに配置する必要がありますか？このような：

public interface IObjectRepository
{
    /// <summary>
    ///    Returns an object from the respository that contains the specified ID.
    /// </summary>
    Object GetObject(int Id);
}

public ObjectRepository : IObjectRepository
{
    /// <summary>
    ///    Retrieves an object from the database that contains the specified ID.
    /// </summary>
    public Object GetObject(int Id)
    {
        Object myData = // Get from DB code.
        return myData;
    }
}

<param>簡単にするために含めませんでした。

それはコメントの良い習慣ですか、それとも別の方法がありますか？インターフェイスのコメントをスキップしますか？

4

3 に答える 3

10

別のファイルでコメントを定義してから、<include>タグを使用できます（MSDNを参照）。このように、コメントを1回だけ書き込むことができますが、複数の異なる場所（たとえば、インターフェイスの宣言と実装）にドキュメントとして含めることができます。

もちろん、これは書くのがより難しいので、もう少し規律が必要です。また、ソースコードに表示されないため、少し便利ではありません。ただし、XMLコメントを使用してドキュメントを作成する場合は、おそらくそれが適切なアプローチです。

于 2011-04-05T21:32:44.130 に答える
3

両方にコメントすることをお勧めします。インターフェイスメソッドの定義には、コンシューマーが実装または呼び出すために必要なすべての情報が含まれている必要があることに注意してください。実装は、どちらを使用するかを選択するだけでなく、消費者にも関係するため、コメントすることも適切です。

肝心なのは、より明確にするというよりも、より明確にするという側面で誤りを犯すことです。

于 2011-04-05T21:40:03.713 に答える
0

インターフェイスを文書化します。

実装がより一般的またはより具体的である場合、たとえば、より広い入力を処理したり、より具体的な出力を返したりスローしたりできる場合は、実装にそれを文書化します。

実装がインターフェースと異ならない場合は、を使用できます<inheritdoc />。

関連：C＃でドキュメントを継承しますか？

于 2018-01-18T17:01:52.373 に答える