Komentar sebelum atau setelah kode yang relevan [ditutup]

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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

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.