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

私たち全員が（私たちが気になることがあるとき！）私たちのインターフェースにコメントしていると思います。例えば

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

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

ありがとう

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

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

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

詳細については：

• 公式のjavadocドキュメント
• いくつかの非公式なアドバイス。

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

C＃の場合はIMOに依存します。明示的なインターフェイス実装を使用する場合、実装についてはドキュメント化しません。

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

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

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

インターフェースにコメントを付けるだけです。コメントは、派生クラスまたは基本クラス/インターフェースと同期しなくなるので、1か所に置くと便利です。

@Nathは、物事をまとめるのに役立つ自動化されたドキュメントツールを提案しているように見えますが（それを使用すれば素晴らしい音がします）。ここWhereIWorkAndYouDontCareのコメントは開発者向けなので、コード内の1つの場所が推奨されます

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

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

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

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

これはwww.inheritdoc.io（無料バージョンあり）にあります。

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

C＃の使用法：

インターフェイスは次のようになります。

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

実装は次のようになります。

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}