Haruskah komentar metode menyertakan ringkasan dan deskripsi pengembalian ketika mereka sering sangat mirip?

Saya seorang pendukung kode yang terdokumentasi dengan baik, dan saya sangat menyadari kemungkinan kerugiannya . Itu di luar ruang lingkup pertanyaan ini.

Saya suka mengikuti aturan menambahkan komentar XML untuk setiap anggota publik, mengingat betapa saya suka IntelliSense di Visual Studio.

Namun ada satu bentuk redundansi, yang bahkan terganggu oleh komentator berlebihan seperti saya. Sebagai contoh, ambil List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summarydan returnspada dasarnya mengatakan hal yang sama. Saya sering berakhir dengan menulis ringkasan dari returnssudut pandang, membuang semua returnsdokumentasinya.

Mengembalikan nilai true ketika Daftar berisi elemen yang cocok dengan kondisi yang ditentukan oleh predikat yang ditentukan, salah jika tidak.

Selain itu, dokumentasi pengembalian tidak muncul di IntelliSense, jadi saya lebih suka menulis informasi yang relevan dengan segera di summary.

1. Mengapa Anda perlu mendokumentasikan returnssecara terpisah summary?
2. Adakah informasi tentang mengapa Microsoft mengadopsi standar ini?

Anda dapat menyimpulkan satu dari yang lain, tetapi kedua bagian itu tetap terpisah, karena membantu memfokuskan pada bagian yang menarik minat orang ketika meninjau / menggunakan kode .

Mengambil contoh Anda, saya lebih suka menulis:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• Jika saya meninjau kode ini dan saya ingin tahu apa metode ini, saya membaca ringkasannya, dan hanya itu yang saya pedulikan.

• Sekarang, mari kita bayangkan saya menggunakan metode Anda dan nilai pengembalian yang saya terima aneh, diberikan input. Sekarang, saya tidak benar-benar ingin tahu apa metode ini, tetapi saya ingin tahu lebih banyak tentang nilai pengembalian. Di sini, <returns/>bagian membantu, dan saya tidak perlu membaca ringkasannya.

Sekali lagi, dalam contoh ini, Anda dapat menyimpulkan ringkasan dari <returns/>, dan menyimpulkan nilai pengembalian yang diharapkan dari ringkasan. Tetapi mengambil argumen yang sama ke ekstrem, tidak perlu mendokumentasikan metode Anda sama sekali dalam hal ini: nama metode, dimasukkan ke dalam List<T>, dengan Predicate<T> matchsebagai satu-satunya argumen itu sendiri cukup eksplisit.

Ingat, kode sumber ditulis sekali tetapi banyak dibaca . Jika Anda dapat mengurangi cukai untuk pembaca kode Anda lebih lanjut, sambil menghabiskan sepuluh detik menulis kalimat tambahan dalam dokumentasi XML, lakukanlah.

Penggunaan saya:
<summary>menjelaskan apa yang dilakukan metode (untuk mendapatkan <returns>).
<returns>menggambarkan nilai pengembalian .

Link ke MSDN: <summary>.<returns>

Mengapa Anda perlu mendokumentasikan pengembalian secara terpisah dari ringkasan?

Saya pikir jika bagian ringkasan sangat panjang dan deskriptif, mungkin berguna untuk memiliki bagian pengembalian yang terpisah dan singkat di bagian akhir.

Saya biasanya menulis hanya <summary>bagian dalam kode saya sendiri, kata-kata seperti yang Anda katakan "Pengembalian _ ".

Saya memberikan pernyataan bahwa seorang penelepon harus tahu yang tidak jelas dari nama metode dan parameter (dan nama mereka). Semoga nama dan parameter metode membuatnya cukup jelas sehingga komentarnya bisa sangat singkat.

Saya telah terkoyak oleh pertanyaan filosofis yang sama belakangan ini dan saya masih tidak yakin apa solusi yang baik. Namun sejauh ini, ini telah menjadi pendekatan saya ...

• Dokumentasi metode hanya menggambarkan apa yang perlu diketahui oleh penelepon eksternal. Itu tidak berbicara tentang bagaimana pekerjaan ini dilakukan secara internal, tetapi menyebutkan a) mengapa penelepon ingin memanggil metode ini, b) apa hasil yang diharapkan dari pemanggilan metode. Jika ada kebutuhan untuk mendokumentasikan bagaimana metode ini bekerja, saya memasukkannya ke dalam tubuh kode itu sendiri.
• Jika suatu metode memiliki kompleksitas yang cukup untuk itu, maka deskripsi umum dan bagian [pengembalian] terpisah tampaknya dibenarkan. Anda tidak ingin pembaca membaca seluruh deskripsi dan mencoba menyimpulkan bagaimana menafsirkan nilai kembali.
• Jika metode ini sangat sederhana sehingga cara terbaik untuk menggambarkan apa yang dilakukannya adalah mengatakan sesuatu seperti "Metode ini mengembalikan alamat orang", maka saya melewatkan bagian [pengembalian] karena menambahkan tampaknya bertentangan dengan prinsip KERING dan saya pendukung besar itu. Banyak metode aksesor satu-liner tampaknya termasuk dalam kategori ini.

Ringkasan tersebut harus bersifat deskriptif yang mungkin bermanfaat; deskripsi parameter dan nilai pengembalian harus pendek dan manis. Jika Anda memiliki pilihan antara satu kata dan lima kata, gunakan satu kata. Mari kencangkan contoh Anda:

true jika Daftar berisi satu atau lebih elemen yang cocok dengan kondisi yang ditentukan oleh predikat yang ditentukan; jika tidak, salah.

menjadi

true jika ada elemen Daftar yang cocok dengan predikat; jika tidak salah.