Apa yang harus saya sertakan dalam komentar dokumentasi XML?

Saya mencoba membuat poin mendokumentasikan kode saya lebih baik, terutama ketika datang ke komentar XML pada anggota kelas, tetapi seringkali itu hanya terasa konyol.

Dalam hal event handler, konvensi penamaan dan parameternya standar dan jelas:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

Saya juga sering memiliki properti sederhana yang (IMO) dinamai dengan jelas sehingga ringkasannya berlebihan:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

Saya tidak merasa komentar seperti itu tidak menambahkan informasi yang belum disampaikan oleh deklarasi itu sendiri. Kebijaksanaan umum tampaknya adalah bahwa komentar yang mengulang kode sebaiknya dibiarkan tidak tertulis.

Jelas, dokumentasi XML lebih dari sekadar komentar kode inline biasa, dan idealnya akan memiliki cakupan 100%. Apa yang harus saya tulis dalam kasus seperti itu? Jika contoh-contoh ini OK, nilai apa yang mereka tambahkan yang mungkin tidak saya hargai sekarang?

Komentar dokumen XML dimaksudkan untuk anggota publik.

The compiler peringatan jelas menyatakan ini:

Komentar XML tidak ada untuk tipe atau anggota yang terlihat secara publik 'Type_or_Member'

Anda hanya harus menambahkan komentar XML ke anggota pribadi jika anggota tersebut belum jelas dari nama mereka.

Pendapat murni di sini, jadi anggaplah itu layak.

Saya benci komentar xml berlebihan. Tidak diragukan lagi untuk hantu gaya doc yang hanya menambahkan spasi ke metode / nama properti. Itu tidak menambah nilai dan hanya mengacaukan pandangan saya tentang kode aktual.

Jika sesuatu membutuhkan klarifikasi, tentu saja, berikan komentar. Namun, banyak kejelasan dapat disampaikan dengan metode fokus kecil dengan nama yang bermakna. Jangan berkomentar kode jika Anda dapat memperbaikinya dan membuat komentar tidak perlu.

Bahkan jangan mulai saya pada penggunaan yang tidak perlu this.dan Me..

Sebagai catatan, saya ingin memiliki addin Visual Studio yang memungkinkan saya mengaktifkan visibilitas komentar xml. (petunjuk, petunjuk)

Pada anggota publik, dokumen XML harus cukup bertele-tele dan lengkap, seperti yang telah disebutkan oleh @SLaks.

Namun mereka dapat benar-benar berguna pada anggota pribadi, terlindungi atau internal juga karena Visual Studio akan mengisi intellisense dan membantu tooltips dengan komentar dokumen XML.

Ini berarti:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Mungkin dokumentasi yang cukup sempurna, tetapi:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Akan jauh lebih mudah dilihat dengan cepat dari tempat lain dalam kode Anda.

Umumnya pada komentar XML publik saya menulis untuk beberapa pengguna eksternal API, dan pada komentar XML internal saya menulis untuk saya atau orang lain di tim saya.

Melewati deskripsi parameter mungkin merupakan ide yang buruk untuk yang pertama dan baik untuk yang terakhir.

Saya akan menambahkan (terutama dalam dokumen API publik) selalu menyertakan apakah getatau setpada properti:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

Tidak jelas dari intellisense C # apakah tersedia getatau settidak, tetapi menaruhnya di komentar XML akan berarti Anda dapat langsung melihat dari tooltip.