Mengapa /// blok komentar penting?


49

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.


1
Saya tidak yakin apakah blok komentar ini adalah preferensi pribadi atau standar yang disarankan
Rachel

1
Saya juga berpikir begitu.
Ryan Hayes

30
Saya pikir ini adalah jenis pertanyaan yang ada di sini. Ada kemungkinan besar bahwa ini akan ditutup pada stackoverflow sebagai subjektif.
Paddyslacker

Gunakan blok <summary> jika Anda ingin menghasilkan dokumentasi. Ini masuk akal jika Anda membuat API untuk digunakan orang lain. Melakukan ini untuk setiap metode berlebihan dan mengurangi fleksibilitas Anda.
Macneil

Jawaban:


91

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


22
+1 Benar-benar menggunakannya. Anda akan terkejut betapa bermanfaatnya memiliki mereka jika Anda pernah menggunakan kembali komponen Anda dan memiliki semua dokumentasi hebat yang tersedia di intellisense.
Walter

4
Juga jika Anda menggunakan Visual Studio dan memulai baris dengan /// tepat sebelum deklarasi kelas, metode, atau bidang, VS akan menghasilkan struktur dokumentasi XML untuk Anda - Anda hanya harus mengisinya. Saya setuju bahwa ini membutuhkan waktu. banyak ruang di layar Anda, tapi itu adalah kompromi yang layak saya katakan. Juga, F # memiliki dukungan yang lebih baik untuk itu (mis. Anda tidak harus menggunakan <summary> dan </summary> karena dianggap 'diasumsikan').
ShdNx

7
Karena jawaban ini sudah merupakan pilihan terbaik saya hanya akan menambahkan komentar saya: Ketika saya mengetahui bahwa ringkasan tersebut digunakan untuk intellisense, dan proyek saya bertambah besar, saya sangat senang telah menemukan fitur ini. Mengingat apa metode dan kelas saya adalah menjadi tantangan besar, dan mendokumentasikan kode melalui mekanisme ini sangat menyederhanakan hal-hal, memungkinkan saya untuk fokus pada kode baru dan resusabilitas alih-alih mencoba mengingat apa yang dilakukan bulan lalu.
JYelton

3
Hanya satu hal untuk ditambahkan, komentar-komentar ini tidak dikompilasi ke dalam dll, Anda harus memberikan file xml terkait dengan dll Anda.
Benjol

Mereka berguna, tetapi mereka membuat kelas saat ini sangat tidak dapat dibaca. Saya berharap ada cara lain yang tidak mengacaukan kode.
Jeroen van Langen

17

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!


1
Tautan ke blog tampaknya mati (pos terakhir 5 tahun yang lalu dengan html rusak di seluruh halaman), dan lokasi proyek telah dipindahkan. Apakah Anda memiliki tautan yang diperbarui untuk Sandcastle?

12

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

    }

11
Sementara saya setuju kode harus mendokumentasikan diri sesering mungkin, saya sarankan menggunakan jenis komentar ini bila memungkinkan (dan lebih sering daripada generik // komentar). /// XML komentar dirancang untuk bekerja dengan IntelliSense, yang dapat membuat pengembangan lebih mudah berbulan-bulan ketika Anda mencoba untuk mengimplementasikan beberapa perpustakaan yang Anda buat dan tidak begitu ingat cara kerjanya lagi.
Matt DiTrolio

2
Dan saya pikir tidak hanya dari perspektif Intellisense, dari perspektif generasi dokumentasi otomatis juga, komentar xml berguna. Tetapi seperti semua komentar, ini hanya masuk akal jika komentar itu sendiri berguna, dan menambah kode yang didokumentasikan sendiri.
Vaibhav

5
Saya setuju bahwa ketika Anda menulis kelas publik dari suatu API atau kerangka kerja, standar pengkodean harus menuntut Anda memasukkan komentar dalam kode sedemikian rupa sehingga IntelliSense dan alat dokumentasi dapat dipasang. Tapi itu tidak semua kode. Selain dari keprihatinan itu, pendekatan yang saya anjurkan di sini adalah, ketika Anda mencoba untuk membuat kode Anda lebih bersih dan lebih jelas, fokuslah pada kode itu sendiri, bukan komentar yang menjelaskan kode tersebut.
azheglov

3
@JYelton: komentar Anda salah mengartikan jawaban saya. Saya menyiratkan lebih banyak nama deskriptif, tetapi tidak terlalu banyak yang bertele-tele, tentu saja bukan pengidentifikasi 60 karakter untuk fungsi publik yang sering disebut. Juga, Anda memiliki apa yang tampaknya merupakan fungsi yang sangat terspesialisasi, tetapi dibutuhkan tipe data yang sangat umum (XmlDocument) - itu adalah satu kode bau. Kemudian, pengidentifikasi 60 karakter Anda menjelaskan "bagaimana" dan bukan "apa" - dari metode publik. Itu bau yang lain. Pesan utamanya adalah: pikirkan dulu tentang kodenya, bukan komentarnya.
azheglov

2
@JYelton Masalah dengan nama metode Anda bukan karena bersifat deskriptif, melainkan menjelaskan setidaknya 2 operasi terpisah dan karenanya harus direactored menjadi setidaknya 2 metode independen.
Neal

4

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.


11
Penamaan adalah satu hal, tetapi daftar batasan pada parameter atau pengecualian yang berpotensi dibuang masih berharga.
Adam Lear

Ya, saya akan mengakui Anda ada benarnya, tetapi sebagian besar waktu batasan parameternya jelas bukan?
John MacIntyre

Tidak yakin saya setuju dengan John. Dengan logika ini, tidak ada metode kerangka .net yang bisa mendapatkan bantuan Intellisense.
Vaibhav

1
@vaibhav - Saya memang mengatakan "Saya akan merekomendasikan menggunakannya di setiap kelas publik, metode, & properti di API, perpustakaan, dll ..." ... yang akan mencakup apa yang Anda bicarakan bukan?
John MacIntyre

1
@ John - aneh, saya berani bersumpah bahwa saya membaca sesuatu yang lain sama sekali ketika saya menulis komentar itu. Karena paragraf kedua Anda persis seperti yang saya katakan di tempat lain di utas ini. Jadi, saya harus memiliki batu di kepala saya untuk menulis komentar itu. Ya saya setuju dengan itu.
Vaibhav

2

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.


1

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.


Komentar basi dapat dianggap sebagai bau kode, terlebih lagi di tingkat ringkasan. Jika pengembang lain mengubah fungsi dan tidak memperbarui ringkasan dari apa yang mereka lakukan, maka orang dapat berargumen bahwa mereka tidak mendokumentasikan pekerjaan mereka dengan benar.
rjzii

1

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.


1

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


0

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.


0

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


0

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

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.