Mengapa /// blok komentar penting?

Seseorang pernah berkata kita harus mengawali semua metode kita dengan /// <summary>blok komentar (C #) tetapi tidak menjelaskan mengapa.

Saya mulai menggunakannya dan menemukan mereka sedikit mengganggu saya, jadi berhenti menggunakannya kecuali untuk perpustakaan dan metode statis. Mereka besar dan saya selalu lupa memperbaruinya.

Apakah ada alasan bagus untuk menggunakan /// <summary>blok komentar dalam kode Anda?

Saya biasanya menggunakan //komentar sepanjang waktu, itu hanya /// <summary>blok saya bertanya-tanya tentang.

Gunakan mereka sebanyak mungkin.

Ya, itu adalah komentar khusus yang menjadi dokumentasi untuk metode ini. Konten <summary>, tag parameter, dll. Yang dihasilkan muncul di intellisense ketika Anda atau orang lain sedang bersiap untuk memanggil metode Anda. Mereka pada dasarnya dapat melihat semua dokumentasi untuk metode atau kelas Anda tanpa harus pergi ke file itu sendiri untuk mencari tahu apa yang dilakukannya (atau mencoba hanya membaca tanda tangan metode dan berharap yang terbaik).

Ya, benar-benar menggunakannya untuk apa pun yang ingin Anda simpan, atau mungkin dibagikan.

Juga, gunakan bersama dengan Sandcastle dan Sandcastle Help File Builder , yang mengambil output XML dan mengubahnya menjadi dokumentasi gaya MSDN yang indah.

Tempat terakhir saya bekerja, kami membuat ulang dokumentasi setiap malam dan menghostingnya sebagai beranda internal. Inisial perusahaan adalah MF, jadi itu MFDN;)

Biasanya saya hanya menghasilkan file .chm, yang mudah dibagikan.

Anda akan terkejut betapa kecanduan Anda mendokumentasikan semuanya setelah Anda mulai melihatnya dalam format MSDN!

Jika standar pengkodean Anda menuntut agar Anda menggunakan komentar tersebut (dan standar pengkodean untuk API atau kerangka kerja mungkin menuntut itu), maka Anda tidak punya pilihan, Anda harus menggunakan komentar tersebut.

Kalau tidak, pertimbangkan dengan serius untuk tidak menggunakan komentar seperti itu. Anda dapat menghindarinya dalam banyak kasus dengan mengubah kode Anda seperti ini:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

untuk

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

untuk

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Penamaan kelas, metode, & properti Anda harus jelas, jadi jika Anda membutuhkannya, itu mungkin bau.

Namun, saya akan merekomendasikan menggunakannya pada kelas publik, metode, & properti apa pun di API, pustaka, dll. Paling tidak, mereka akan menghasilkan dokumen untuk membantu pengembang mana pun menggunakannya, dan akan mencegah Anda memiliki untuk menulisnya.

Tapi bagaimanapun Anda mengirisnya, mempertahankannya atau menghapusnya.

Jika Anda harus tetap kembali dan mengedit komentar agar sesuai dengan kode baru, Anda mungkin melakukan kesalahan pada awalnya. Elemen ringkasan harus berisi persis itu - ringkasan - apa dan mengapa hal yang dirangkum Anda.

Menjelaskan cara kerja sesuatu dalam komentar melanggar KERING. Jika kode Anda tidak cukup deskriptif sendiri, mungkin Anda harus kembali dan menolak.

Ya, saya sudah membuatnya. [saat membangun sistem baru dari awal]

Tidak, saya tidak pernah mendapat manfaat dari mereka. [saat bekerja pada sistem yang ada yang membutuhkan pemeliharaan]

Saya menemukan bahwa komentar "Ringkasan" pada akhirnya cenderung tidak sinkron dengan kode. Dan begitu saya melihat beberapa komentar yang berperilaku buruk, saya cenderung kehilangan kepercayaan pada semua komentar pada proyek itu - Anda tidak pernah yakin mana yang harus dipercaya.

Lupa melakukan sesuatu tidak membuatnya menjadi ide yang buruk. Lupa memperbarui dokumentasi apa pun adalah. Saya menemukan ini sangat berguna dalam pemrograman saya dan orang-orang yang mewarisi kode saya berterima kasih memilikinya.

Ini adalah salah satu cara yang paling terlihat untuk mendokumentasikan kode Anda.

Sangat menyebalkan harus menemukan kode sumber untuk membaca dokumentasi inline atau menggali dokumen yang membahas apa yang dilakukan kode. Jika Anda dapat memiliki sesuatu yang berguna muncul melalui kecerdasan maka orang akan mencintaimu.

" Itu harus Digunakan Sangat banyak, seperti aku;) "

Saya biasa bermain dengan komentar (///). Untuk kelas Anda cukup melakukan komentar seperti ini

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Tetapi, untuk suatu metode Anda dapat menambahkan lebih banyak dengan memberikan deskripsi untuk parameter dan jenis kembali.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Anda dapat menggunakan jalan pintas untuk membuat komentar ini (///+Tab).

menggunakannya kecuali untuk perpustakaan

Itulah saatnya mereka berguna. Dengan generasi Dokumentasi XML dihidupkan dan referensi ke majelis, tanpa proyeknya, akan menampilkan detail lebih dalam intellisense.

Tetapi untuk internal proyek saat ini, mereka hanya menghalangi.

Saya menggunakannya, tetapi karena beberapa orang mengatakan tidak secara universal. Untuk metode kecil, mereka dapat dengan mudah lebih besar dari kode yang mereka jelaskan. Mereka sangat berguna untuk menghasilkan dokumentasi yang dapat diberikan kepada orang yang baru mengenal sistem sehingga mereka memiliki sesuatu untuk dijadikan rujukan saat mempelajarinya. Meskipun, sebagai programmer, kita biasanya dapat mencari tahu apa beberapa kode karena itu baik untuk memiliki komentar untuk membimbing kita dan bertindak sebagai penopang. Jika memiliki harus ditulis di suatu tempat kemudian dalam kode adalah tempat kemungkinan besar untuk tinggal diperbarui (lebih mungkin dibandingkan beberapa dokumen Word mengambang sekitar).

Saya menggunakan yang setara dalam VB (karena mereka tidak akan membiarkan saya menggunakan C # - tampaknya itu terlalu sulit ... tidak ada komentar.) Saya merasa sangat nyaman. Sebagian besar waktu saya menunggu sampai prosedur atau fungsi selesai sebelum memasukkannya, jika hanya untuk menghindari keharusan mengubah komentar - atau meminta mereka "tidak sinkron".

Saya tidak perlu menulis novel - hanya dasar-dasar, deskripsi parameter dan beberapa komentar (biasanya ketika ada sesuatu yang "luar biasa" terjadi di sana - solusi atau omong kosong lain yang saya lebih suka tidak ada di sana tetapi memiliki tidak ada pilihan "untuk sekarang".) (Ya, saya tahu, bahwa "untuk saat ini" dapat bertahan bertahun-tahun.)

Saya sangat kesal dengan kode uncommented. Seorang konsultan menulis versi awal dari salah satu komponen kami dan tidak mengomentari apa pun dan pilihan namanya akan diinginkan di sana-sini. Dia sudah lebih dari setahun dan kami masih memilah barang-barangnya (selain mengerjakan barang-barang kami sendiri.)