Apakah Anda menulis judul dalam komentar kode? [Tutup]

17

Saya sedang menelusuri beberapa kode lama yang saya tulis (tahun pertama di universitas) dan memperhatikan bahwa saya biasa menulis judul komentar sebelum berbagai bagian kode. Hal-hal seperti (ini dari permainan Monopoli):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Ini mungkin berlebihan, dan bisa dibilang tidak perlu jika kodenya benar-benar sangat jelas, tetapi ketika saya memindai melalui file itu mengejutkan saya betapa kuatnya saya merasa seperti saya tahu apa yang terjadi walaupun saya hampir tidak melihat kode yang sebenarnya. Saya pasti bisa melihat ini pas dalam keadaan tertentu, jadi saya ingin tahu - apakah Anda melakukan ini? Apakah Anda pikir itu ide yang bagus? Atau terlalu banyak?

EpsilonVector
sumber

Jawaban:

24

Ini bau kode. Ini mengatakan apa dan bukan mengapa .

Jika perlu, bagi kode menjadi fungsi-fungsi kecil.

Maniero
sumber
4
Tidak ada gunanya memiliki fungsi untuk memiliki fungsi.
Paul Nathan
30
benar: jika kode layak komentar seperti /*Board initialization*/, mungkin harus dalam fungsi yang disebut InitializeBoard. Jika struktur kode Anda cukup jelas maka Anda tidak perlu komentar.
Tim Robinson
3
"Apa" itu baik untuk diketahui, dan seringkali tidak jelas dari melihat kode. Komentar-komentar ini memperjelas maksud keseluruhan.
DarenW
4
@ DarenW - tetapi begitu juga fungsi / prosedur / metode. Dan yang belakangan memiliki manfaat tambahan dari memodulasi kode, yang membuatnya lebih mudah untuk dipahami .
Stephen C
3
Manfaat lain dari ini adalah bahwa fungsi-fungsi seperti InitializeBoardatau InitializePlayerakan muncul dalam daftar browser fungsi / modul / kelas dari sebagian besar IDE sedangkan komentar tidak. Navigasi yang lebih mudah.
Steve Fallows
13

Saya melakukan itu sepanjang waktu. Keduanya untuk menandai apa yang dilakukan kode, dan mungkin yang lebih penting, seperti yang Anda katakan, agar mudah untuk memindai & menemukan sepotong kode. Kadang-kadang, juga, saya akan menuliskan proses yang terlibat dalam komentar, dan 'mengisi' kode di bawah komentar ketika saya pergi.

GrandmasterB
sumber
7
+1 - kejelasan adalah hal yang baik. Saya tidak setuju dengan jawaban yang disetujui yang mengatakan ini adalah bau kode. Jika itu menambah kejelasan - lakukanlah.
cepat_now
2
Jika itu melanggar OAOO, maka jangan lakukan itu. Ini berlebihan, dan cenderung tidak sinkron dengan kode yang didokumentasikannya. Masukkan kode ke dalam suatu fungsi dan beri nama fungsi dengan apa yang dilakukannya. IDE modern memudahkan untuk mengubah nama fungsi dan memperbarui semua referensi. Dengan begitu semua instance tetap terkini.
Scott Whitlock
3
+1 dari saya. Dalam file kode besar, saya ingin memiliki lebih dari sekadar spasi putih yang memisahkan bagian logis. Ya, saya pikir jika fungsi Anda loooooong maka Anda perlu membaginya, tetapi saya merasa jauh lebih mudah untuk membaca jika bagian dipisahkan oleh komentar.
Anthony
6

Saya merasa menarik betapa banyak orang tidak menyukai latihan ini tanpa benar-benar dapat mengartikulasikan mengapa. Alasan mengapa komentar seperti itu tidak disukai adalah mereka adalah tanda bahwa Anda telah melanggar prinsip tanggung jawab tunggal. Nama spesifik itu biasanya hanya digunakan dalam konteks OO, tetapi konsep umum juga disebut kohesi dan berlaku untuk paradigma lain. Sekolah biasanya tidak mengajarkan prinsip-prinsip desain semacam itu sampai menjelang akhir program gelar, jika memang ada. Bahkan, beberapa guru mengamanatkan pelanggarannya untuk membuat segalanya lebih mudah untuk dinilai dengan menjejalkan semuanya menjadi satu file. Oleh karena itu, ketidaktahuan mahasiswa baru Anda dapat dimaafkan, dan fakta bahwa Anda memperhatikan "sesuatu" salah dan mencoba untuk mengklarifikasi dengan komentar bahkan patut dipuji dalam situasi tersebut, tetapi secara umum lebih baik untuk memperbaiki desain yang tidak jelas daripada mencoba untuk melapisinya dengan komentar.

Karl Bielefeldt
sumber
4

Saya melihat hal-hal ini sebagai cara untuk membuat kode lebih jelas atau tidak. Jika Anda dapat mengetahui berdasarkan metode dalam file apa setiap bagian maka tidak perlu namun jika Anda harus memiliki beberapa bagian maka itu dapat bermanfaat. Mungkin ketika file kode menjadi terlalu besar itu perlu dipecah yang dapat mengurangi kebutuhan akan komentar seperti itu.

Saya akan mengatakan jika bekerja dalam tim untuk menghasilkan standar sehingga Anda semua setidaknya mengkode dan berkomentar dengan cara yang sama sehingga melihat kode menjadi lebih mudah.

aqwert
sumber
3

Saya melakukan ini karena saya sering mengomunikasikan niat untuk diri saya sendiri, atau pada dasarnya menempatkan bookmark yang nyaman untuk hal-hal seperti "Pembersihan data dimulai di sini". Biasanya di bawah judul itu ada sedikit penjelasan singkat tentang logika apa yang saya lakukan dan mengapa.

Saya suka redundansi. Jika saya kehilangan buku catatan laboratorium saya karena satu dan lain alasan, atau harus meninjau kembali kode yang saya tulis bertahun-tahun yang lalu, saya tidak suka harus menyatukan apa yang saya lakukan dan mengapa saya melakukannya. Jika setidaknya beberapa dari logika itu ada dalam kode, itu cukup didokumentasikan bagi saya untuk setidaknya bekerja dengannya lagi.

Saya pikir bagian dari kecenderungan saya terhadapnya adalah jumlah yang wajar dari pemrograman saya bersifat statistik, dan dengan demikian agak berulang. Sedangkan mungkin ada beberapa potong kode di mana saya punya fungsi bernama membantu untuk mencari, saya mungkin memiliki beberapa lusin penggunaan yang agak mirip dari sesuatu seperti fungsi model linier umum. Sangat berguna untuk dapat pergi dan menemukan yang mana dari kode "seberapa sensitif hasil untuk Pilihan A vs Pilihan B atau C", dan mana yang lain. Itu sering dipercepat oleh judul.

Fomite
sumber
Komentar yang menyatakan tujuan bisnis / tujuan tingkat tinggi sangat bermanfaat. Mereka memungkinkan konfirmasi & dukungan pengertian. Tes unit dapat diklaim sebagai redundan juga - saya akan menyarankan bahwa mendokumentasikan & memahami kode setidaknya sama pentingnya dengan mengujinya.
Thomas W
2

Saya pikir itu berguna dalam situasi di mana Anda memiliki file sumber raksasa dengan puluhan fungsi dan Anda dapat mengaturnya menjadi potongan-potongan seperti itu. Saya tidak mengatakan saya suka itu lebih baik daripada file sumber yang lebih kecil, lebih fokus ...

μBio
sumber