Apakah ada metode untuk membedakan komentar informatif dari kode yang dikomentari?

38

Sepanjang program, Anda akan berakhir dengan beberapa komentar yang menjelaskan kode dan beberapa komentar yang menghapus kode:

// A concise description 
const a = Boolean(obj);
//b = false;

Apakah ada metode yang baik untuk mem-parsing yang mana?

Saya telah bermain-main dengan menggunakan 3 /dan /** */untuk komentar deskriptif.

Saya juga menggunakan plugin VSCode untuk menyorot //TODO:dan//FIXME:

javascript comments

— Kartu as
sumber

2

Sebagai catatan, ///dan /** ... */komentar juga digunakan oleh beberapa generator dokumentasi, seperti Doxygen atau JSDoc. Jika Anda menggunakannya atau alat serupa, Anda mungkin tidak dapat menggunakan komentar semacam itu untuk komentar deskriptif yang tidak dimaksudkan untuk menjadi bagian dari dokumentasi.

— Justin Time 2 Reinstate Monica

1

Dalam javascript, sebagian besar baris kode mungkin akan diakhiri dengan tanda titik koma. Kecuali jika komentar Anda melakukannya, itu tampaknya cukup sederhana, dan Anda dapat menulis skrip untuk memeriksanya dengan mudah juga;

— Artemis Fowl

189

Ada solusi yang sangat sederhana untuk ini: hapus kode komentar.

Sungguh, hanya ada dua alasan bagus untuk mengomentari kode: untuk menguji sesuatu / melakukan perbaikan, atau untuk menyimpan kode yang mungkin Anda gunakan nanti. Jika Anda menguji atau memperbaiki sesuatu, hapus kode yang berkomentar segera setelah Anda selesai dengan tes atau perbaiki. Jika Anda menyimpan kode yang mungkin Anda gunakan nanti, buatlah kode kelas satu dan letakkan di suatu tempat seperti perpustakaan di mana dapat dimanfaatkan dengan baik.

— Robert Harvey
sumber

108

Juga, jika kode telah dicentang: hapus saja. Jika Anda membutuhkannya kembali, kontrol sumber membuat Anda terlindungi

— marstato

38

Ketika kode dihapus, tidak ada yang memperhatikannya. Itu membuatnya lebih sulit untuk pulih. Ada nilai dalam meninggalkan kode yang dikomentari, terutama jika tampaknya akan digunakan di masa depan.

— usr

76

@ Usr: Ketika kode dihapus, tidak ada yang tahu bahwa kode itu pernah ada - dan menurut pengalaman saya, dalam 99% dari semua kasus di dunia nyata itu adalah hal yang benar. Dalam 1%, mungkin ada beberapa nilai di baris outcommented, namun, jika kode berkomentar tetap selama beberapa minggu atau bulan (atau lebih lama), kemungkinan besar itu bahkan tidak dapat dikompilasi lagi karena refactor dari aktif baris kode. Argumen "nilai pontensial untuk penggunaan di masa depan" sering digunakan sebagai alasan yang salah oleh orang-orang yang memiliki masalah emosional dengan menghilangkan hal-hal dari basis kode yang telah mereka investasikan beberapa jam untuk kerja otak.

— Doc Brown

21

Saya tidak pernah melakukan kode komentar tanpa komentar penjelasan tambahan. Ada situasi yang jarang terjadi di mana Anda mungkin ingin kode kembali dalam waktu dekat, tetapi setiap satu dari mereka adalah luar biasa dan memerlukan penjelasan untuk pengembang masa depan (atau masa depan Anda). 90% dari komentar saya adalah "Dihapus karena tampaknya tidak digunakan. Hapus setelah November 2021 jika tidak ada masalah"

— James Beninger

31

Rekan saya pernah meletakkan "Ada kode di sini yang melakukan X tapi saya menghapusnya" ketika kami menghapus beberapa fitur untuk saat ini. Itu bekerja dengan sangat baik; Anda tahu itu dalam riwayat sumber untuk file itu, tetapi itu tidak mengganggu Anda.

— Erik

45

Menambahkan ke jawaban yang sangat bagus dari @ RobertHarvey, saya percaya hanya ada satu alasan sah yang pernah saya temui untuk menyimpan kode komentar ke kontrol sumber, bahkan untuk sementara: dalam kasus kode pengganti yang tidak jelas yang tidak boleh atau tidak dapat digunakan sekarang karena alasan tertentu . Meski begitu sebagian besar komentar harus penjelasan, bukan kode penggantian. Ini bisa berupa bug atau fitur bahasa yang belum dianggap stabil. Mungkin terlihat seperti ini:

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

Dalam hal ini, pekerjaan sudah dilakukan, tetapi Anda belum bisa memanfaatkannya, jadi menghapusnya berarti seseorang harus menemukan kembali nanti. Hal yang sama berlaku untuk solusi suboptimal yang mungkin tampak lebih unggul di hadapannya atau pertukaran timbal balik dengan solusi serupa .

Perhatian: Jangan membuang kode Anda dengan solusi alternatif. Setiap tugas dapat dilakukan dengan berbagai cara tanpa batas, dan tidak hemat biaya untuk menjelajahi ruang ini untuk waktu yang lama untuk setiap perubahan. Ulasan kode dapat menjadi tempat yang baik untuk menemukan komentar yang hilang tersebut, ketika kolega Anda menyarankan perbaikan yang Anda temukan tidak optimal.

— l0b0
sumber

2

Sisi sebaliknya dari ini adalah bahwa kadang-kadang Anda perlu menjelaskan mengapa Anda tidak menggunakan frobnicate(bar), sehingga tidak ada yang akan datang dan mencoba untuk "memperbaiki" kode Anda "tidak berlaku". Jadi Anda menunjukkan kepada mereka bahwa Anda tahu bahwa di dunia yang sempurna, frobnicatefungsinya akan menjadi jalan yang harus ditempuh, tetapi Anda tahu dari pengalaman yang menyakitkan itu tidak bekerja dengan benar. Mungkin tidak ada harapan sama sekali bahwa pihak ketiga bahkan menganggapnya sebagai bug, apalagi diperbaiki; Anda masih perlu memberikan komentar kepada programmer masa depan (termasuk diri Anda) tentang mengapa Anda tidak mengambil pendekatan yang jelas.

— Monty Harder

3

Situasi terkait adalah bahwa mungkin ada dua cara untuk melakukan sesuatu, salah satunya akan memproses data yang valid lebih cepat daripada yang lain, dan satu di antaranya akan menawarkan diagnostik yang lebih bermanfaat jika, karena alasan apa pun, ia menerima data yang tidak valid. Jika program tersebut merupakan bagian dari proses yang seharusnya hanya memberi makan data yang "dijamin" valid, tetapi sesuatu dalam proses tersebut tidak berfungsi dengan baik, karena tersedia versi yang lebih lambat, tetapi menawarkan diagnostik yang lebih baik, dapat membuatnya lebih mudah untuk menentukan apa yang salah.

— supercat

20

Hmm, saya membaca pertanyaan ini sedikit berbeda dari Robert yang dengan benar menyatakan bahwa kode yang dikomentari harus dihapus.

Namun, jika Anda mencari konvensi untuk menandai kode untuk dihapus nanti, favorit lama saya adalah:

//b = false; //TODO: remove

Beberapa flag IDE //TODO:berkomentar atau dapat diajarkan. Jika tidak, biasanya itu adalah string yang dapat dicari. Yang terbaik adalah mengikuti konvensi apa pun yang telah dibuat oleh toko Anda karena ini dapat dilakukan dengan beberapa cara. Setiap basis kode harus melakukan ini dengan satu cara. Tetap dicari.

cepat parse yang mana?

Tanpa tanda itu cara otomatis untuk melakukan ini adalah dengan kompiler. Jika menghapus komentar menghasilkan kode yang mengkompilasi, itu pasti kode yang berkomentar. Menulis plugin IDE yang memeriksa itu tidak akan sulit. Tapi itu akan meninggalkan kode komentar kereta di belakang.

Inilah sebabnya mengapa lebih baik hanya menandai kode yang dikomentari sebagai kode saat Anda berkomentar. Ini memungkinkan Anda bekerja tanpa merusak saat Anda memutuskan apakah Anda benar-benar ingin itu hilang. Karena kita semua terganggu, dan agak pelupa, jangan heran jika beberapa baris diperiksa saat dalam keadaan itu. Jika mereka melakukannya itu bagus bahwa mereka setidaknya ditandai dengan jelas dan dapat dicari. Makro keyboard telah membantu saya dengan ini di masa lalu. Sulit untuk terganggu di tengah-tengah ini jika Anda dapat melakukannya dengan satu ketukan.

Anda dapat mengambil ini sejauh mengabadikan tanda dalam tes integrasi berkelanjutan Anda. Ups, saya mencoba memeriksa dengan TODO yang luar biasa lagi.

— candied_orange
sumber

Alih-alih melihat apakah komentar dikompilasi untuk melabeli mereka sebagai kode, Anda dapat menjalankan komentar melalui pengolah bahasa alami dan memberi label yang menguraikan sebagai kalimat atau frasa kata benda dalam bahasa yang dibicarakan tim Anda.

— TheHansinator

3

@TheHansinator yang kedengarannya bagus tetapi pengalaman saya dengan ponsel saya memperbaiki hubungan dengan jargon coder saya membuat saya berhati-hati.

— candied_orange

Saya membayangkan bahwa NLP yang digunakan untuk menguraikan komentar kode akan jauh lebih baik daripada NLP yang memberdayakan koreksi otomatis, hanya karena komputer memiliki seluruh kalimat untuk bekerja dan tidak mencoba memperbaiki kesalahan pengejaan. Belum lagi bahwa negatif palsu juga lebih baik di sini - selama manusia dapat meninjau komentar sebelum dihapus, mereka hanya dapat menulis ulang komentar, sebagai lawan dari tidak disiagakan kepada gobbledygook yang tidak berguna.

— TheHansinator

3

wrt parsing: double buffer (flip on)-> C prototipe atau bahasa Inggris ultra-singkat? tidak bisa membedakan tanpa konteks, bukan keseluruhan konstruksi yang benar dalam kedua bahasa. Beberapa positif dan negatif palsu tidak dapat dihindari, ketika komentar pada dasarnya tidak membatasi bentuk konten mereka di kedua arah.

— Leushenko

8

Saya menggunakan arahan preprosesor untuk menghapus kode, bukan komentar sama sekali:

//comment
active_code();
#if FALSE
inactive_code();
#endif

Ini membuat hal yang sangat mudah untuk dicari, dan stabilo sintaksis saya memperlakukannya sebagai komentar. Saya bahkan dapat menciutkannya menjadi satu baris:#if FALSE(...)

Anda dapat memperluas gagasan itu untuk memiliki beberapa opsi:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

Dan kompilasi pengecekan kesalahan waktu:

#if FOO >= 5
#error FOO should be less than 5!
#endif

Tentu saja, Anda tidak ingin berlebihan dalam hal ini, atau menjadi sulit untuk mengatakan apa yang sebenarnya dikompilasi dan apa yang tidak. Tetapi Anda mendapatkan idenya, dan itu adalah masalah yang sama seperti untuk kode yang dikomentari ... selama Anda hanya menggunakannya secara statis. Jika kondisi Anda dinamis, itu lebih buruk.

Untuk menentukan yang mana dalam basis kode yang ada yang tidak mempertimbangkan masalah ini sama sekali, saya tidak berpikir ada solusi universal. Anda harus menemukan pola sendiri dan mungkin kode regex untuk menemukannya.

— AaronD
sumber

Untuk apa dunia ini berguna? Apakah Anda perlu mengkompilasi beberapa versi?

— Tvde1

@ Tvde1 Itu ini satu kemungkinan, dan mimpi buruk potensial jika Anda tidak mengelola itu benar-benar baik. Tetapi alternatifnya mungkin lebih buruk. Jika Anda memiliki banyak salinan dengan kode yang hampir sama, satu untuk setiap variasi pada tema umum, maka Anda harus memeliharanya secara terpisah dan tetap menyinkronkannya.

— AaronD

Ada beberapa cara untuk melakukan ini, tetapi mereka semua memiliki beberapa variasi baik dari masalah konfigurasi kompleks atau masalah salinan independen: Apakah Anda yakin bahwa perbaikan bug sampai ke semua salinan independen? Bagaimana jika tidak, dan fitur lain ditambahkan, yang kemudian rusak oleh perbaikan bug yang diketahui sebelum fitur tetapi tidak porting sampai sekarang?

— AaronD

3

Itu hanya berfungsi jika Anda memiliki langkah pra-pemrosesan seperti C. Pertanyaannya adalah tentang javascript. Anda dapat melakukan beberapa pra-pemrosesan tetapi akan memperluas kemampuan sistem build dan juga non-standar. Jika Anda tidak memiliki sistem build atau sistem build sama sekali tidak mendukung parsing dan mengeksekusi kode, Anda tidak akan dapat mengimplementasikan solusi ini. Akhirnya, bahkan tidak menjawab pertanyaan - kode yang dikomentari tidak sepenuhnya setara dengan kode yang diaktifkan secara kondisional. Bisa jadi itu adalah sisa yang tidak dimaksudkan untuk diaktifkan.

— VLAZ

Aktivasi bersyarat hanyalah perpanjangan dari jawaban dan bukan jawaban itu sendiri. Kalau tidak, saya akan mengeditnya untuk memasukkan komentar yang meluas lebih jauh.

— AaronD

4

Saya setuju dengan jawaban yang menyatakan bahwa kode lama harus dihapus daripada dikomentari jika memungkinkan, namun saya telah mengamati konvensi untuk beberapa kesempatan ketika kode berkomentar diperlukan.

(Basis saya adalah C # tetapi ini dapat diterapkan ke bahasa sintaksis C misalnya java)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}

— IanF1
sumber

2

Ini sepenuhnya tergantung pada gaya: Ketika saya mengomentari kode, saya biasanya menambahkan //ke kolom pertama, dan karena hampir semua kode diindentasi, hasilnya hampir selalu bahwa komentar dimulai dengan beberapa tab. Komentar normal tidak mendapatkan ruang terdepan dari saya, kecuali sudah ada komentar lain dengan ruang terdepan di sekitarnya. Jadi, metode Anda akan gagal total pada komentar yang saya hasilkan, dan metode apa pun yang dirancang untuk mengenali pola komentar saya akan gagal parah pada Anda.

— cmaster

@ cmaster Ah saya mengerti, saya pikir saya salah mengerti pertanyaan itu. Saya memberikan cara sederhana untuk memformat komentar sedemikian rupa sehingga mereka dapat dengan mudah diuraikan untuk jenis, yang bukan apa yang diminta.

— IanF1

2

Saya masih menafsirkan pertanyaan yang berbeda, berpikir Anda ingin menemukan kode komentar.

Kode C-style pasti memiliki semi-titik dua di dalamnya sementara komentar tidak mungkin memiliki semi-titik dua di dalamnya. Jadi untuk satu baris kode komentar Anda dapat menggunakan ekspresi reguler ini:

\s*\/\/[\s\S]*;

Untuk kode komentar multi-baris bisa jadi

\/\*[^\;]*;[^\;]*\*\/

Catatan Visual Studio agak aneh tentang jeda baris dalam ekspresi reguler, mereka tidak dihitung sebagai spasi putih, Anda perlu menentukan \ n eksplisit.

— Martin Maat
sumber

2

Jika Anda menggunakan editor dengan kompiler berjalan di latar belakang (seperti Xcode dan Dentang), Anda bisa mencoba mengkompilasi teks komentar. Misalnya "deskripsi ringkas" memberikan kesalahan, "b = false;" tidak. Anda kemudian dapat menggunakan berbagai penyorotan sintaksis.

Metode yang lebih sederhana adalah plugin IDE yang menggunakan beberapa heuristik, seperti beberapa kata dalam satu baris selain dari kata kunci yang menunjuk pada komentar, pencocokan titik kurung kurawal untuk kode dll.

— gnasher729
sumber

1

Jawaban lain mencakup variasi pada tema "jangan komentar kode". Tetapi kadang-kadang Anda masih menginginkannya untuk referensi.

Jika Anda benar-benar membutuhkan kode untuk tetap bertahan, solusi yang lebih baik adalah mengelilingi kode dengan "#jika 0 ... #endif", idealnya dengan komentar untuk mengatakan alasannya. Ini adalah strategi yang direkomendasikan dari berbagai standar pengkodean, termasuk MISRA.

— Graham
sumber

-3

Sederhana, setidaknya untuk saya - dan di C / C ++. Komentar terlampir di / * * / informatif. Kode uji yang dihapus sementara dikomentari dengan memimpin //.

Dan ada alasan bagus untuk meninggalkan kode tes dalam file tetapi berkomentar, setidaknya dalam jenis pekerjaan yang saya lakukan. Cepat atau lambat seseorang akan menginginkan perubahan yang dibuat, yang membutuhkan kode itu. Membatalkan komentar blok membutuhkan satu perintah editor, seperti halnya mengomentari ulang di mana Anda selesai.

— jamesqf
sumber

Ada juga #ifdef __DEBUG ... #endif, atau definisi khusus apa pun yang ingin Anda gunakan. __DEBUGitu bagus, karena Anda sering hanya perlu mengubah konfigurasi proyek untuk mendapatkannya. Tetapi sebagian besar IDE memungkinkan Anda menentukan konfigurasi Anda sendiri, yang dapat memberi Anda apa pun di tempat itu.

— AaronD

Apa yang Anda maksud dengan "kode uji"? Tes unit? Itu tidak boleh dikomentari sama sekali tetapi disimpan di ruang uji dan berjalan sesering mungkin, terlepas dari apakah seseorang berpikir itu perlu. Tentu, mudah untuk kembali mengomentari sepotong kode, tetapi lebih mudah untuk tidak melakukan apa-apa dan memiliki test suite sudah siap melakukannya ...

— leftaroundabout

1

Argh, jangan lakukan itu. Mengomentari kode "untuk menguji sesuatu" akan berfungsi dengan sangat baik 99 dari 100 kali ... dan dalam satu kasus Anda akan lupa untuk menghapusnya (jika tidak diperlukan lagi) atau - lebih buruk lagi - lupa untuk menghapus komentar itu ( jika diperlukan) dan segala sesuatunya menjadi jelek.

— CharonX

@ Leftaroundabout: Tidak, maksud saya hal-hal seperti pernyataan printf dimasukkan untuk memeriksa nilai.

— jamesqf

@ jamesqf Anda seharusnya tidak perlu hal-hal semacam itu, itulah gunanya debugger. Tetapi bahkan jika Anda menggunakan printf/ coutatau serupa untuk mendapatkan kode yang baru ditulis dengan benar (yang saya akui telah saya lakukan sendiri di masa lalu), itu benar-benar tidak terlalu efektif untuk membiarkan mereka di sana. Jika seseorang ingin membuat perubahan dan mengetahui variabel mana yang mereka butuhkan info tentang, itu cepat dan mudah untuk menulis printflagi, sedangkan jika dev itu tidak tahu apa yang dibutuhkan dan hanya komentar-komentar semua printfpernyataan itu maka petak besar teks di terminal kemungkinan juga tidak akan membantu mereka.

— leftaroundabout