Apakah Anda menulis judul dalam komentar kode? [Tutup]

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?

Ini bau kode. Ini mengatakan apa dan bukan mengapa .

Jika perlu, bagi kode menjadi fungsi-fungsi kecil.

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.

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.

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.

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.

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