web-dev-qa-db-ja.com

インターフェイス、実装、またはその両方にコメントしますか？

私たち全員が（私たちが悩むことができるとき！）私たちのインターフェースをコメントすることを想像します。例えば.

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

実装についてコメントしますか（これは、たとえばライブラリの一部としてクライアントに提供されることもあります）？その場合、2つの同期をどのように維持しますか？または、「ドキュメントのインターフェイスを見る」コメントを追加するだけですか？

ありがとう

c#javacommentsinterface
117
ng5000

一般的なルールとして、コードと同じDRY（Do n't Repeat Yourself）原則を使用します。

  • インターフェイスで、インターフェイスを文書化する
  • 実装時に、実装の詳細を文書化する

Java固有：実装を文書化するとき、{@ inheritDoc}タグを使用して、インターフェースからjavadocsを「含める」。

詳細については：

91
Neeme Praks

GhostDoc アドインを使用する場合、メソッドで右クリックして[これをドキュメント化]を選択すると、インターフェイスからのコメントで実装が更新されます。

7
NikolaiDante

C＃の場合、IMOに依存します。明示的なインターフェイス実装を使用する場合、実装を文書化しません。

ただし、インターフェイスを直接実装し、インターフェイスのメンバーをオブジェクトで公開する場合、これらのメソッドも文書化する必要があります。

Nathが言ったように、GhostDocを使用して、インターフェイスのドキュメントを実装に自動的に挿入できます。 DocumentこのコマンドをCtrl + Shift + Dショートカットと、ほぼ自動的に押すキーストロークの1つにマッピングしました。 ReSharperには、メソッドを実装するときに、インターフェイスのドキュメントを挿入するオプションもあると思います。

5
grover

インターフェースにコメントを付けるだけです。コメントは派生クラスまたは基本クラス/インターフェースのいずれかと簡単に同期できなくなるため、1か所にまとめておくと便利です。

@Nathはおそらく、物事をまとめるのに役立つ自動化されたドキュメントツールを提案しているように見えます（それを使用する場合はクールに聞こえます）。 WhereIWorkAndYouDontCareでは、コメントは開発者向けであるため、コード内の単一の場所が優先されます

4
Jiminy

インターフェイスのみ。両方のコメントは重複しているため、コードが変更されると、2つのコメントセットが最終的に同期しなくなる可能性があります。 「実装MyInterface」で実装にコメントします... Doxygenのようなものは、とにかく実装のドキュメントに派生ドキュメントを含むドキュメントを生成します（正しくセットアップした場合）。

3
Len Holgate

実際の実装の使用方法を理解するには、インターフェースにコメントを付けるだけで十分です。実装にコメントを追加するのは、インターフェイスを満たすために挿入されたプライベート関数がある場合だけです。ただし、それらは内部のみのコメントであり、オンラインのドキュメントやクライアントが利用することはできません。

実装は、インターフェイスに準拠している限り、個別に文書化する必要はありません。

2
X-Istence

XMLドキュメントファイルを後処理して<inheritdoc />タグのサポートを追加するツールを作成しました。

ソースコードのIntellisenseには役立ちませんが、変更されたXMLドキュメントファイルをNuGetパッケージに含めることができるため、参照されたNuGetパッケージのIntellisenseで動作します。

Www.inheritdoc.io（無料版が利用可能）にあります。

0
K Johnson

確かに両方をコメントすることはできますが、両方を維持するという問題があります（前述のとおり）。しかし、今日では、実際にIoC/DIを使用せず、インターフェイスを使用しない消費コードがありますか？これを考慮して、1つだけコメントする場合は、インターフェイスにコメントすることを強くお勧めします。このようにして、コードのコンシューマーはニースインテリセンスのヒントを得ることができます。

0
bytedev