Panduan pemula untuk menulis komentar?

27

Apakah ada panduan yang pasti untuk menulis komentar kode, yang ditujukan untuk pengembang pemula?

Idealnya, itu akan mencakup kapan komentar harus (dan tidak boleh) digunakan, dan komentar apa yang harus berisi.

Jangan berkomentar APA yang Anda lakukan, tetapi MENGAPA Anda melakukannya.

WHAT dirawat dengan kode yang bersih, mudah dibaca, dan sederhana dengan pilihan nama variabel yang tepat untuk mendukungnya. Komentar menunjukkan struktur level yang lebih tinggi ke kode yang tidak dapat (atau sulit untuk) ditunjukkan oleh kode itu sendiri.

datang dekat, tapi itu sedikit ringkas untuk programmer yang tidak berpengalaman (perluasan pada itu dengan beberapa contoh dan kasus sudut akan sangat baik, saya pikir).

Pembaruan : Selain jawaban di sini, saya pikir jawaban untuk pertanyaan lain ini sangat relevan.

language-agnostic comments Cameron
sumber

Saya pikir kita dengan cepat pindah ke dunia di mana orang tidak berkomentar lagi. Untuk yang lebih baik (lebih mungkin) lebih buruk. Tangkas.

MK01

1

@MK: Jika itu masalahnya (saya cenderung lebih setuju dengan jawaban ini ), maka panduan yang menjelaskan bagaimana tidak menulis komentar, dan mengapa mereka harus dihindari, akan sama bermanfaatnya. Sebenarnya, semakin banyak sudut pandang yang berbeda, semakin baik.

Cameron

Saya pikir komentar kecil untuk meningkatkan kecepatan membaca kode sangat membantu dan akan selalu demikian. Saya tidak sepenuhnya membeli alasan "komentar basi", bahkan jika mereka basi, mereka akan memiliki nilai historis. Saya dulu bekerja pada basis kode yang kadang-kadang memiliki komentar rinci di sana-sini dan tidak pernah benar-benar digigit oleh komentar karena masalah yang sudah ketinggalan zaman.

MK01

lihat juga: "Komentar adalah bau kode"

agas

38

Anda harus menyadari kelemahan terbesar dari komentar: mereka menjadi basi. Artinya, seiring perubahan kode, pengembang jarang memperbarui komentar agar tetap sinkron dengan kode. Ini berarti, Anda tidak akan pernah bisa mempercayai mereka dan masih membaca kode. Karena alasan inilah, kode Anda harus mendokumentasikan diri sendiri. Anda harus memilih fungsi dan nama variabel Anda sedemikian rupa sehingga kode dibaca seperti prosa.

Jadi jangan dokumentasikan APA yang dilakukan kodenya. Kode yang mendokumentasikan diri sendiri harus memperhatikan hal itu. Dokumentasikan MENGAPA Anda melakukannya. MENGAPA biasanya terkait dengan aturan bisnis atau terkait arsitektur dan tidak akan sering berubah dan menjadi basi secepat apa. Pelindung tepi dokumen. Pengecualian dokumen. Mendokumentasikan keputusan desain. Dan yang paling penting mendokumentasikan keputusan desain yang Anda pertimbangkan, tetapi memutuskan untuk tidak menerapkan (dan mendokumentasikan mengapa Anda memutuskan untuk tidak menggunakannya).

sumber

2

Yang terakhir sangat penting. Terkadang ada bug / efek samping dengan menerapkan solusi yang jelas. Mendokumentasikan mengapa Anda memilih untuk pergi dengan beberapa solusi lain mencegah pengembang berikutnya dari memperkenalkan kembali bug ketika mereka "memperbaiki" Anda solusi yang tampaknya buruk.

CaffGeek

2

Poin lain, pekerjaan pertama saya menganggap komentar sama pentingnya dengan kode. Cobalah untuk membiasakan diri membaca komentar dan juga kode ketika Anda melakukan peer review, dan cobalah untuk bersikeras bahwa komentar tersebut selalu mutakhir jika memungkinkan. Ini membantu menghindari komentar menjadi basi dan membuat aturan bisnis, dll. Didokumentasikan dalam kode Anda terbaru.

Eric Hydrick

10

Anda harus membaca buku Clean Code Robert C. Martin . Ini menjelaskan dengan baik bahwa jika Anda memerlukan komentar, kemungkinan besar Anda tidak mengkode dengan benar. Idealnya, kode Anda harus "berkomentar sendiri." Buku Clean Coder menjelaskan cara melakukan ini, sehingga komentar tidak diperlukan, dan itu menjelaskan dengan baik bagaimana melakukan komentar dalam situasi di mana diperlukan. (Seperti menjelaskan rumus matematika yang kompleks)

Bob
sumber

Meskipun saya tidak ingin rumus matematika yang rumit dijelaskan karena saya ingin itu ditulis dalam notasi matematika yang tepat (mungkin TeX), dengan penjelasan tentang pentingnya dan sumbernya. Jika Anda tidak mengerti rumusnya maka Anda tidak boleh main-main dengan kode yang menggunakannya untuk menghitung nilai, karena Anda kemungkinan besar akan mengacau dan memperkenalkan bug (halus atau tidak).

CVn

Kode hanya dapat mengatakan bagaimana , bukan mengapa atau mengapa tidak . Anda perlu komentar untuk itu.

7

Kode Lengkap, sebagaimana disebutkan, memiliki berbagai panduan tentang menulis komentar. Singkatnya, ini PDL dan dapat disimpulkan sebagai:

Jelaskan maksud Anda, bukan apa yang dilakukan kode. Hindari mendeskripsikan detail implementasi kecuali Anda menggunakan beberapa trik atau Anda menggunakan implementasi kustom. Misalnya, menggunakan bit bergeser untuk membagi, menggunakan aritmatika pointer untuk mengakses anggota kelas atau menggunakan pengalokasi memori khusus untuk beberapa objek yang dikumpulkan.
Tuliskan kode pseudo (mis., Komentar) terlebih dahulu, kemudian tulis kode sesungguhnya setelah Anda selesai menggambarkan rutinitas / metode / fungsi Anda. Bahasa yang digunakan adalah tingkat tinggi namun spesifik, sehingga bisa agak verbal
Pikirkan apa yang dilakukan kode Anda bahkan sebelum menulis kode
Berikan komentar sedekat kode sebenarnya

Tujuannya adalah untuk menghindari komentar yang tidak berhubungan panjang lebar yang mungkin sudah ketinggalan zaman, tetapi memiliki komentar yang mencerminkan maksud dan tujuan dari kode. Menggunakan kode pseudo tingkat tinggi juga membantu memperjelas pemikiran Anda sebelum menulis implementasinya.

Ada tautan di GameDev.net [yang menjelaskan PDL] [1], jika Anda tidak ingin melacak buku tersebut.

Extrakun
sumber

5

Tulis kode pseudo (yaitu komentar) terlebih dahulu . Saya tidak bisa tidak setuju lagi. Tidak ada cara yang lebih baik untuk memastikan komentar tidak cocok dengan kode. Coders baru (dan penanya yang secara khusus meminta panduan pemula) akan meretas dan memfungsikan fungsi seratus kali sebelum mereka senang dengan mereka, kode akan dipindahkan dengan cepat, ditulis ulang, diarahkan ulang dan pada akhirnya, mereka dapat memiliki solusi kerja yang elegan, tetapi tidak akan seperti kode pseudo awal mereka. Apakah komentar akan dipindahkan dan diperbarui saat kode berfungsi? Anda bisa bertaruh bippy manis Anda mereka tidak akan. Dua sen saya.

Binary Worrier

1

Juga, komentar kode semu akan memberi tahu Anda apa yang seharusnya dilakukan oleh kode tersebut. Kode harus memberi tahu Anda hal itu. Kode semu tidak akan memberi tahu Anda mengapa kode melakukannya. -1 Bung, maaf, tapi saya tidak bisa setuju dengan poin kedua, waktu telah berubah.

Binary Worrier

1

Bukan untuk berdebat, tetapi lebih banyak penjelasan - kode pseudo adalah untuk menjelaskan maksud dari kode yang telah Anda tulis. Artinya, komentar ini bukan tentang detail implementasi (Seperti "Tambah x ke atas tumpukan") tetapi lebih tentang apa yang seharusnya dilakukan oleh kode (seperti "Buat jendela muncul di depan yang lainnya"). Seperti yang telah Anda tunjukkan dengan benar, Anda perlu memindahkan komentar dengan kode tersebut. Saya tidak setuju dengan kode yang dapat memberi tahu Anda apa yang dilakukan kode - sepanjang waktu. Sekalipun, komentar yang membantu / akurat (jika saya berhasil menulisnya dengan baik!) Sangat membantu. Pada akhirnya, masih IMHO.

Extrakun

3

Suatu metode atau fungsi yang dipanggil showWindowOnTop(window)akan selalu lebih baik daripada komentar yang sifatnya sama, semua ini sudah ketinggalan zaman dan saran yang buruk pada tahun 2012. 1) Nama fungsi / Metode menggambarkan maksud, 2) kode pseudo adalah latihan berongga dengan rantai alat modern 3) Pengujian memberi tahu Anda apa yang seharusnya dilakukan oleh kode sebelum Anda menulisnya, 4) kode dengan nama baik lebih baik daripada komentar yang tidak cocok dengan kode dengan nama buruk

6

Saya hanya mengikuti satu prinsip sederhana dan umum: Komentar Anda seharusnya tidak mengatakan apa yang dilakukan kode, tetapi mengapa itu melakukannya. Martin Fowler Artikel dan Buku tentang Re-factoring dan Kode. Buku lengkap memiliki banyak informasi, tetapi sayangnya itu tidak dalam bentuk ringkasan untuk pengetahuan saya.

Shahzeb
sumber

1

Saran saya adalah menulis beberapa kode tanpa komentar apa pun, dan kemudian berjalan menjauh darinya. Kembalilah ke sana dalam setahun dan bacalah. Bagian yang tidak mudah Anda pahami adalah bagian yang seharusnya Anda komentari.

Kevin
sumber

1

Hah, ya ;-) Ini bukan saran yang sangat membantu - mungkin ini seharusnya komentar?

Cameron

bagian yang tidak Anda mengerti seharusnya Anda tulis di bagian yang lebih kecil dan lebih baik. Alasan utama komentar dimasukkan ke dalam kode adalah fungsi / metode yang panjang dan harus banyak potongan kecil yang mendokumentasikan diri.

0

Saya sangat suka bagaimana Evan Todd merangkum pandangannya tentang satu-satunya kategori komentar yang berguna ( mengutip dari blognya ):

Komentar menjelaskan mengapa, bukan apa. Ini yang paling bermanfaat.

Komentar dengan beberapa kata menjelaskan apa yang dilakukan oleh sepotong kode raksasa berikut. Ini berguna untuk navigasi dan membaca.

Komentar dalam deklarasi struktur data, menjelaskan apa artinya masing-masing bidang. Ini seringkali tidak perlu, tetapi kadang-kadang tidak mungkin untuk memetakan konsep secara intuitif ke memori, dan komentar diperlukan untuk menggambarkan pemetaan.

Cameron
sumber

Panduan pemula untuk menulis komentar?

Jawaban: