Komentar sebelum atau setelah kode yang relevan [ditutup]


34

Dengan asumsi komentar tidak sesuai (atau tidak bisa) pada baris yang berlaku, haruskah seseorang menulis komentar sebelum kode atau setelahnya?

Nah, di mana pun pembaca di masa depan akan lebih memahami ruang lingkup komentar. Dengan kata lain, di mana pun kebanyakan programmer / penulis naskah memberikan komentar seperti itu.

Jadi di mana sebagian besar programmer / skrip memberi komentar: sebelum atau sesudah kodenya?

Jika jawaban Anda hanya berlaku untuk bahasa tertentu, harap tunjukkan yang mana.

Dan jika Anda dapat mengutip spesifikasi atau panduan yang diterima yang mendukung jawaban Anda, jauh lebih baik.


3
Mempertimbangkan apa yang terjadi ketika Anda mengejarnya. Programmer membaca kodenya. Katakan pada dirinya sendiri apa yang sedang dilakukan WTF ??? Lihat komentarnya. Baca kode lagi. Kadang memahaminya atau menyerah. Jadi bersikap baik dan hindari bagian 1 dan 2 dengan meletakkannya di atas.
deadalnix

@deadalnix, terima kasih, yang tampaknya menjadi inti dari jawaban Dipan Mehta juga. (Terima kasih juga untuk semua penjawab sejauh ini, dan +1 untuk masing-masing.)
msh210

Jawaban:


22

Saya akan memberikan komentar sebaris atau sebelum kode komentar berlaku. Arti komentar adalah untuk mendapatkan pemahaman dasar apa yang dilakukan kode, tanpa perlu membaca kode itu sendiri. Jadi jauh lebih masuk akal untuk menempatkan komentar sebelum kode yang dijelaskan.

Microsoft mengatakan itu akan menjadi praktik pemrograman yang baik untuk memulai prosedur dengan komentar kecil. (Mereka tidak menyebutkan komentar setelah prosedur) MSDN Tautan ini tentang VisualBasic tetapi itu berlaku untuk sebagian besar bahasa pemrograman yang saya pikir.


1
Tanda centang, karena ini adalah satu-satunya jawaban (sejauh ini) yang dengan jelas menjawab pertanyaan, yang mencari bukan preferensi pribadi tetapi prosedur operasi standar, dalam hal ini mengutip MSDN.
msh210

1
@ msh210: Jadi, Anda lebih suka preferensi Microsoft daripada preferensi pribadi programmer lain yang baik? TAPI Anda tahu bagaimana Microsoft membuat Notasi Hongaria salah sebagai standar? Iya nih? Apakah kamu? Hanya percaya akal sehat, jangan selalu lari dengan gerombolan atau ikuti banteng terbesar.
Falcon

2
@ Falcon, saya belum pernah mendengar Notasi Hongaria, dan saya menduga preferensi MSDN setidaknya hasil dari sekelompok masukan karyawan MS; jawaban di sini, sebaliknya, ditulis secara individual.
msh210

43

Saya lebih suka komentar berada di atas kode yang mereka rujuk, lebih masuk akal untuk memberi tahu seseorang membaca kode tentang apa yang akan terjadi daripada mencoba merujuk ke kode sebelumnya untuk menjelaskan bahwa beberapa baris kode yang berantakan memperbaiki beberapa bug yang rumit jadi jangan menyentuhnya.


9

Saya pikir kode umumnya dibaca dari atas ke bawah. Jika tidak ada yang lain, memori otot akan menyebabkan saya mengaitkan komentar dengan baris kode berikutnya di bawahnya.


7

Biasanya komentar harus di TOP dari baris berikut lekukan yang sama dengan karya. Misalnya, komentar di atas isi fungsi, dan komentar satu liner tepat di atas permulaan algoritma kritis.

Alasannya adalah, ketika seseorang mulai membacanya, menjadi pertanyaan yang jelas bahwa mengapa sesuatu dilakukan sedemikian rupa; sedangkan orang tersebut tidak tahu sampai titik mana seseorang perlu mencari jawabannya. Jika di atas, itu ada di sana untuk dilihat.


6

Jadi di mana sebagian besar programmer / skrip memberi komentar: sebelum atau sesudah kodenya?

Dalam bertahun-tahun pemrograman menggunakan berbagai bahasa, saya tidak ingat melihat kode dalam bahasa apa pun di mana komentar ditempatkan pada baris baru setelah kode yang merujuknya. Di AS, setidaknya, standar de facto berkomentar sebelum kode atau pada baris yang sama mengikuti kode. Menulis komentar Anda setelah kode terkait mengundang tes narkoba, evaluasi kejiwaan, dan / atau kencan dengan sepasang tang dan obor tiup.

Satu-satunya pengecualian yang dapat saya pikirkan adalah komentar yang menandai akhir dari bagian yang sebelumnya dikomentari, seperti ini:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin menulis esai yang dipertimbangkan dengan baik pada komentar yang layak dibaca. Dia tidak mengatakan apakah dia meletakkan komentarnya sebelum atau setelah kode, tetapi dia mengatakan bahwa dia tidak pernah memasukkannya, dan saya berani bertaruh banyak uang bahwa dia juga tidak meletakkannya setelah itu.


4

Cobalah berkomentar hanya jika benar-benar diperlukan; kode harus berusaha mendokumentasikan diri sendiri jika memungkinkan.

Karena itu, penempatan dapat bergantung: Jika Anda menggunakan baris terpisah untuk komentar, letakkan di depan kode aktual. Jika Anda memilikinya di baris yang sama, letakkan setelah itu.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Tapi tidak pernah:

int i = 0;
// this workaround is required to make the compiler happy


Baca kembali pertanyaannya: itu menentukan pertanyaan tentang komentar di baris terpisah.
msh210

2
@ msh210 Ini adalah jawaban yang sempurna. "tulis komentar sebelumnya". Itu bahkan lebih rinci dan memberikan kemungkinan alasan mengapa Anda mungkin berpikir mereka mengejar "Kecuali jika mereka pendek dan berada di ujung garis."
rds

3

Saya sebenarnya bukan penggemar komentar. Selama kursus rekayasa perangkat lunak, saya diperkenalkan dengan gagasan tentang kode yang mendokumentasikan diri. Kode adalah satu-satunya yang dijamin 100% dokumentasi yang benar dari dirinya sendiri - komentar perlu diperbarui, dibangun dengan hati-hati dan relevan, jika tidak mereka adalah perangkap yang bisa lebih buruk daripada tidak ada komentar. Baru setelah saya mulai bekerja di sebuah toko C ++ dengan panduan gaya yang ketat dan konvensi penamaan yang berarti saya benar-benar menginternalisasi konsep ini.

Terkadang komentar diperlukan. Sering kali, penamaan variabel yang cermat, penggunaan ruang putih dan pengelompokan yang bermakna, dan organisasi logis yang bermakna dari kode itu sendiri menghilangkan kebutuhan akan komentar.

Ini benar-benar merupakan negasi dari kepura-puraan dan validitas pertanyaan Anda, sebagai lawan dari jawaban untuk pertanyaan yang Anda miliki. Saya masih berpikir itu relevan dan dapat membantu Anda, dan saya tidak brengsek. Jika tidak, -1 akan mendominasi saya.


10
Kode yang didokumentasikan sendiri dapat menjawab "apa" dan "bagaimana", tetapi tidak peduli seberapa baik ditulis, kode itu sendiri jarang dapat menjawab pertanyaan "Mengapa?". Jika ada dokumen persyaratan yang komprehensif, Anda terkadang dapat menemukan jawabannya di sana. Kalau tidak, komentar sering kali Anda harus menjelaskan mengapa kode perlu melakukan apa yang dilakukannya.
Ed Staub

1
Saya tidak setuju. Seperti yang dikatakan @EdStaub, berkomentar menjawab pertanyaan yang berbeda, pada tingkat yang berbeda. Juga kode tidak harus open-source. Dan bahkan ketika itu, saya tidak ingin membaca kode sumber kerangka kerja untuk mengetahui cara menggunakannya.
rds

4
Anda jelas tidak pernah berurusan dengan perangkat keras (atau berinteraksi dengan perangkat lunak yang ditulis dengan buruk, baik). Baru-baru ini saya selesai menulis kelas khusus untuk berbicara dengan pengendali motor yang agak tidak jelas (dan rewel ). Ini memiliki segala macam persyaratan aneh untuk berinteraksi. Pendeknya memiliki satu fungsi per baris, tidak ada cara untuk membuat kode dapat dimengerti tanpa berkomentar.
Nama Palsu

3
@ Brian, "Mengapa" pertanyaan yang sering sangat halus-grained - misalnya, mendapatkan sekitar bug dalam API, dan / atau menjelaskan bahwa sesuatu yang terlihat salah sebenarnya benar. Itu hanya beberapa contoh. Saya tidak akan membuat komentar menjadi dokumen persyaratan yang komprehensif. Tetapi saya juga tidak akan mencoba menjelaskan alasan untuk setiap detail implementasi kecil dalam spesifikasi persyaratan (atau bahkan spesifikasi desain, dalam hal ini).
Ed Staub

1
@codesparkle - Saya setuju bahwa komentar yang digunakan sebagai alasan untuk menghindari refactoring umumnya buruk. Namun, ini tidak berarti bahwa semua komentar itu buruk, hanya saja komentar yang disalahgunakan sedemikian rupa. Faktanya adalah, ada sejumlah situasi di mana komentar benar-benar merupakan pilihan terbaik untuk memperjelas persyaratan pengkodean yang aneh.
Nama Palsu

2

Memiliki komentar yang muncul sebelum kode membantu pembaca memiliki konteks untuk kode yang akan mereka temui. Jauh lebih manusiawi daripada melemparkan kode pada mereka dan menjelaskan setelah mereka sudah bingung.


2

OK, saya akan membuat kasus "setelah": kode harus selalu menjadi dokumentasi utama, sedangkan komentar (yang tidak memiliki makna semantik) seperti penjelasan kurung. Jadi menempatkan komentar di bawah kode yang membutuhkan penjelasan meninggalkan kode sebagai penjelasan utama, dan hanya menggunakan komentar untuk klarifikasi. Contohnya,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Jika Anda meletakkan komentar sebelum ujian, pembaca akan cenderung membaca komentar sebagai hal utama dan mungkin tidak membaca kode dengan cermat, tidak menyadari bahwa mereka telah disesatkan:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

5
Kedua blok kode Anda memiliki komentar sebelum kode yang mereka komentari.
msh210

komentar Anda sendiri meniadakan "after case" hehe :) pelukan dan +1 untuk menjadikannya contoh bertema natal
Ahmed Masud

1
@ msh210 Saya melihat komentar saya dalam contoh pertama sebagai mengomentari tes if (natal), bukan sebagai "tentang" fungsi-fungsi berikut (yaitu, mereka mengatakan "apa artinya kita di sini?") Mereka mendahului blok kode, tetapi saya belum pernah melihat kode yang memiliki ... code (); kode(); / * komentar yang menjelaskan blok sebelumnya * /} dan tidak menjawab pertanyaan seperti itu
Larry OBrien

1

Untuk meminjam beberapa ide dari penulisan teknis (setidaknya dalam bahasa Inggris), hal-hal seperti catatan dan peringatan peringatan biasanya ditempatkan sebelum instruksi atau bagian yang berlaku untuk catatan atau peringatan peringatan.

Saya tidak melihat mengapa kode tidak dapat dianggap sebagai bentuk penulisan teknis - setiap blok adalah instruksi. Seperti bahasa Inggris, sebagian besar bahasa pemrograman dibaca dari kiri ke kanan, atas ke bawah. Komentar adalah catatan tentang kode - mereka mungkin mengidentifikasi kesalahan untuk diperbaiki, atau hal-hal yang mungkin perlu disadari oleh pengembang di masa depan.

Setelah hubungan ini, tampaknya lebih tepat untuk meletakkan komentar di atas blok kode yang dimaksud.


1

Sebuah komentar mungkin perlu pergi di atas atau di bawah sepotong kode, tergantung pada jenis komentar itu: jika memberikan penjelasan yang sangat singkat tentang apa yang dilakukan kode, maka perlu mendahului kode; jika secara terperinci menjelaskan rincian teknis tentang cara kerja kode, maka perlu mengikuti kode.

Untungnya, sebuah komentar dapat berupa potongan kode di atas atau di bawah, dan tetap tidak meragukan bagian kode mana yang terkait, dengan memanfaatkan baris kosong dengan benar. Tentu saja, programmer yang tidak memperhatikan penggunaan baris kosong tidak akan tahu apa yang saya bicarakan; jika Anda salah satunya, lewati jawaban ini dan lanjutkan hidup Anda. Tetapi programmer yang memperhatikan baris kosong tahu betul bahwa baris kosong digunakan untuk membagi kode menjadi entitas logis. Jadi, jika Anda melihat yang berikut:

[blank line]
/* comment */
{ code }
[blank line]

Anda tahu bahwa komentar itu milik kode itu, dan itu memberi tahu Anda apa yang dilakukannya. Sedangkan, jika Anda melihat yang berikut:

[blank line]
{ code }
/* comment */
[blank line]

Sekali lagi Anda tahu betul bahwa komentar itu milik kode itu, dan itu adalah klarifikasi tentang bagaimana kode melakukan apa yang dilakukannya.


Seperti yang selalu saya katakan: downvote Anda tanpa penjelasan tidak membantu saya menjadi orang yang lebih baik. Saya juga mencintaimu!
Mike Nakis

1

Komentar di atas adalah yang terbaik.

jika Anda harus memasukkan komentar dan kode Anda tidak jelas, maka saya lebih suka tidak bingung dengan blok kode, kemudian lihat "ahh, itu yang seharusnya dilakukan".

Kode dapat (dan seharusnya) menjadi "mendokumentasikan diri sendiri", tetapi jika Anda harus membaca dan memahami setiap baris kode untuk memahami cara kerja suatu metode. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Ketika saya sudah goggle tentang topik ini, saya menemukan bahwa sebagian besar sistem dokumentasi yang dapat dibaca komputer (Doc XML, Doxygen, Java doc dll) mengharapkan komentar untuk muncul sebelum kode yang terkait - lebih baik tetap kompatibel dengan standar itu.

Saya juga setuju dengan utas SO - Haruskah kita menambahkan komentar setelah blok kode, daripada sebelumnya? ..

Saya juga lebih suka tahu di depan ...


1

Saya sering mengubah komentar (milik saya dan juga ditulis oleh orang lain) menjadi laporan log tingkat jejak. Ini biasanya membuatnya lebih mudah untuk memahami di mana menempatkannya.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Keuntungan tambahan adalah bahwa ketika menjadi sulit saya dapat mengaktifkan penelusuran log dan mendapatkan log eksekusi lebih rinci.

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.