Mengomentari antarmuka, implementasi, atau keduanya?

Saya membayangkan bahwa kita semua (ketika kita bisa diganggu!) Mengomentari antarmuka kita. misalnya

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

Apakah Anda juga berkomentar implementasi (yang juga dapat diberikan kepada klien, misalnya sebagai bagian dari perpustakaan aa)? Jika demikian, bagaimana Anda mengatur agar keduanya tetap sinkron? Atau apakah Anda hanya menambahkan komentar 'Lihat antarmuka untuk dokumentasi'?

Terima kasih

Sebagai aturan umum, saya menggunakan prinsip KERING (Jangan Ulangi Diri Sendiri) yang sama dengan kode:

• pada antarmuka, dokumentasikan antarmuka
• pada implementasi, dokumentasikan spesifik implementasi

Khusus Java : saat mendokumentasikan implementasi, gunakan tag {@inheritDoc} untuk "memasukkan" javadocs dari antarmuka.

Untuk informasi lebih lanjut:

• Dokumentasi javadoc resmi
• Beberapa saran tidak resmi .

Jika Anda menggunakan add -in GhostDoc , pembaruan implementasi dengan komentar dari antarmuka ketika Anda mengklik kanan dan pilih "Dokumen Ini" pada metode.

Untuk C # itu tergantung IMO: Jika Anda menggunakan implementasi antarmuka eksplisit, maka saya tidak akan mendokumentasikan implementasinya.

Namun jika Anda mengimplementasikan antarmuka secara langsung dan mengekspos anggota antarmuka dengan objek Anda maka metode ini juga harus didokumentasikan.

Seperti yang dikatakan Nath, Anda dapat menggunakan GhostDoc untuk secara otomatis memasukkan dokumentasi antarmuka ke dalam implementasi. Saya memetakan perintah Dokumen Ini ke Ctrl + Shift + D shortcut dan salah satu penekanan tombol yang saya tekan secara otomatis. Saya percaya ReSharper juga memiliki opsi untuk memasukkan dokumentasi antarmuka, saat mengimplementasikan metode untuk Anda.

Antarmuka saja. Mengomentari keduanya adalah duplikasi dan kemungkinan kedua set komentar pada akhirnya akan keluar dari sinkronisasi jika kode berubah. Komentari implementasi dengan "implementasikan MyInterface" ... Hal-hal seperti Doxygen akan menghasilkan dokumen yang menyertakan dokumen turunan ke dalam dokumen untuk implementasi (jika Anda mengaturnya dengan benar).

Kami hanya berkomentar antarmuka, komentar sangat mudah untuk keluar dari sinkronisasi dengan baik turunan atau kelas dasar / antarmuka yang bagus untuk memilikinya hanya di satu tempat.

Walaupun sepertinya @Nath mungkin menyarankan alat dokumentasi otomatis yang membantu menyatukan segala sesuatunya (kedengarannya keren jika Anda menggunakannya). Di sini, di WhereIWorkAndYouDontCare, komentar untuk dev jadi satu tempat dalam kode lebih disukai

Mengomentari antarmuka harus cukup dokumentasi untuk mengetahui bagaimana menggunakan implementasi yang sebenarnya. Satu-satunya waktu saya akan menambahkan komentar untuk implementasi adalah jika memiliki fungsi pribadi yang dimasukkan untuk memenuhi antarmuka, namun mereka hanya akan komentar internal dan tidak akan terlihat dalam dokumentasi online atau tersedia untuk klien.

Implementasinya hanya itu, selama mereka sesuai dengan antarmuka tidak perlu mendokumentasikannya secara terpisah.

Saya membuat alat yang memposting-proses file dokumentasi XML untuk menambahkan dukungan untuk tag <inheritdoc />.

Meskipun tidak membantu dengan Intellisense dalam kode sumber, ia memungkinkan file dokumentasi XML yang dimodifikasi untuk dimasukkan dalam paket NuGet dan karenanya bekerja dengan Intellisense dalam paket NuGet yang direferensikan.

Ada di www.inheritdoc.io (versi gratis tersedia).

Anda tentu dapat mengomentari keduanya tetapi kemudian Anda memiliki masalah untuk mempertahankan keduanya (seperti yang disebutkan sebelumnya). Namun, di zaman sekarang ini, apakah ada kode yang benar-benar tidak akan menggunakan IoC / DI dan tidak menggunakan antarmuka? Mengingat ini jika Anda hanya ingin mengomentari salah satu saya akan sangat menyarankan mengomentari antarmuka. Dengan cara ini konsumen kode Anda kemungkinan besar akan mendapatkan petunjuk intellisense yang bagus.

Penggunaan C #:

Antarmuka dapat terlihat seperti ini:

    /// <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();
    }
}

Implementasinya dapat terlihat seperti ini:

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