it-swarm-id.com

Mengapa /// blok komentar penting?

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

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, hanya saja /// <summary> blok yang saya tanyakan.

49
Rachel

Gunakan sebanyak mungkin.

Ya, itu adalah komentar khusus yang menjadi dokumentasi untuk metode ini. Isi <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).

91
Ryan Hayes

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 yang indah, gaya MSDN.

Tempat terakhir saya bekerja, kami membuat ulang dokumentasi setiap malam dan meng-host-nya sebagai laman 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!

17
Tom Morgan

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 menghindari mereka 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 ) {

    }
12
azheglov

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

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

Tapi bagaimanapun Anda mengirisnya, merawatnya atau menghapusnya.

4
John MacIntyre

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 - the what dan why dari hal yang diringkas oleh Anda.

Menjelaskan bagaimana sesuatu berfungsi di komentar melanggar KERING. Jika kode Anda tidak cukup deskriptif sendiri, mungkin Anda harus kembali dan menolak.

2
Nobody

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 telah menemukan bahwa komentar "Ringkasan" pada akhirnya cenderung tidak sinkron dengan kode. Dan begitu saya perhatikan beberapa komentar yang berperilaku buruk, saya cenderung kehilangan kepercayaan pada semua komentar pada proyek itu - Anda tidak pernah yakin mana yang harus dipercaya.

1
Preets

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.

Sungguh menyakitkan 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.

1
Abe Miessler

"Itu Harus Digunakan Sangat banyak, seperti saya;)"

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).

1
Sreekumar P

Saya menggunakan yang setara dalam VB (karena mereka tidak akan membiarkan saya menggunakan C # - ternyata itu terlalu sulit ... tidak ada komentar.) Saya merasa sangat nyaman. Sebagian besar waktu saya menunggu sampai prosedur atau fungsinya cukup banyak diselesaikan 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.)

0
MetalMikester

menggunakannya kecuali untuk perpustakaan

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

Tetapi untuk internal proyek saat ini, mereka hanya menghalangi.

0
Richard

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 bagus untuk memiliki komentar untuk membimbing kita dan bertindak sebagai penopang. Jika telah untuk ditulis di suatu tempat maka dalam kode adalah tempat itu kemungkinan besar akan tetap diperbarui (lebih mungkin daripada beberapa dokumen Word yang beredar).

0
Todd Williamson