it-swarm-id.com

Apakah kode yang dikomentari benar-benar selalu buruk?

Praktis setiap teks pada kualitas kode yang saya baca setuju bahwa berkomentar kode adalah hal yang buruk. Contoh biasa adalah seseorang mengubah satu baris kode dan meninggalkan baris lama di sana sebagai komentar, tampaknya membingungkan orang yang membaca kode nanti. Tentu saja, itu hal yang buruk.

Tetapi saya sering menemukan diri saya meninggalkan kode yang dikomentari dalam situasi lain: Saya menulis algoritma komputasi-geometri atau pemrosesan gambar. Untuk memahami kode semacam ini, dan untuk menemukan potensi bug di dalamnya, sering kali sangat membantu untuk menampilkan hasil antara (mis. Menggambar sekumpulan titik ke layar atau menyimpan file bitmap). Melihat nilai-nilai ini di debugger biasanya berarti melihat dinding angka (koordinat, nilai piksel mentah). Tidak terlalu membantu. Menulis visualizer debugger setiap kali akan berlebihan. Saya tidak ingin meninggalkan kode visualisasi di produk akhir (itu menyakitkan kinerja, dan biasanya hanya membingungkan pengguna akhir), tetapi saya juga tidak ingin kehilangannya. Di C++, saya bisa menggunakan #ifdef untuk mengkompilasi kode itu secara kondisional, tapi saya tidak melihat banyak perbedaan antara ini:

/* // Debug Visualization: draw set of found interest points
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
*/

dan ini:

#ifdef DEBUG_VISUALIZATION_DRAW_INTEREST_POINTS
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
#endif

Jadi, sebagian besar waktu, saya hanya membiarkan kode visualisasi dikomentari, dengan komentar yang mengatakan apa yang sedang divisualisasikan. Ketika saya membaca kode setahun kemudian, saya biasanya senang saya hanya bisa menghilangkan tanda komentar pada kode visualisasi dan secara harfiah "melihat apa yang terjadi".

Haruskah saya merasa buruk tentang itu? Mengapa? Apakah ada solusi yang unggul?

Pembaruan: S. Lott bertanya dalam komentar

Apakah Anda entah bagaimana "menggeneralisasi secara berlebihan" semua kode yang dikomentari untuk menyertakan debugging dan juga kode usang yang tidak masuk akal? Mengapa Anda membuat kesimpulan yang terlalu umum?

Saya baru-baru ini membaca Robert Martins "Kode Bersih", yang mengatakan:

Beberapa praktik sama menjijikkannya dengan kode komentar. Jangan lakukan ini!.

Saya telah melihat paragraf dalam buku ini lagi (hlm. 68), tidak ada kualifikasi, tidak ada perbedaan yang dibuat antara berbagai alasan untuk berkomentar kode. Jadi saya bertanya-tanya apakah aturan ini terlalu menggeneralisasi (atau jika saya salah memahami buku) atau apakah yang saya lakukan adalah praktik yang buruk, untuk beberapa alasan saya tidak tahu.

53
nikie

Manfaat # ifdef sebagai lawan mengomentari itu, adalah bahwa (pada proyek-proyek besar) Anda dapat memiliki definisi yang tercantum dalam file make atau config - dan jadi tidak perlu secara manual membuka hal-hal komentar, membangun, dan kemudian kembali -menawarkan mereka jika di banyak tempat. Kelemahan dari ini adalah bahwa mengubah DEFINE proyek biasanya akan berarti membangun kembali semuanya, bukan hanya mengubah file.

Meskipun ... Saya pikir "kode yang dikomentari adalah hal yang buruk" benar-benar merujuk pada kode mati bahwa orang tidak ingin menghapus untuk alasan apa pun (takut membuang sesuatu yang telah mereka habiskan waktu mungkin?). Ini sebenarnya bukan tentang situasi yang Anda alami untuk Anda.

58
TZHX

Jika itu dikomentari, maka itu mungkin membusuk: ketika Anda tiba-tiba memutuskan bahwa Anda membutuhkannya lagi, Anda menyadari bahwa itu tidak lagi mengkompilasi, atau perlu ditulis ulang agar sesuai dengan hal-hal lain yang telah berubah pada saat itu.

Jika Anda membiarkan kode, tetapi sedemikian rupa sehingga kompiler dapat mengoptimalkannya jika tidak diperlukan, maka Anda mendapat manfaat dari menjaga kode tetap up-to-date dan tidak harus menderita biner yang ditambahkan ukuran atau kinerja runtime.

Misalnya, dalam C, ini berisiko busuk:

/*
doSomeDebugStuff();
*/

Demikian juga ini:

#if 0
doSomeDebugStuff();
#endif

Tapi ini bagus, karena selalu diperiksa validitasnya oleh kompiler, tetapi kemungkinan akan dioptimalkan:

if (0)
{
  doSomeDebugStuff();
}

Sunting: seperti yang ditunjukkan orang lain, menggunakan simbol yang bermakna alih-alih 0 untuk ujian bahkan lebih baik.

25
Graham Borland
// The problem with commented out code is that it can hide what you're actually
// trying to say in a wall of text.  Syntax highlighting may help, but you're 
// still left with this huge ginormous wall of text in front of you, searching
// through it for what the actual answer is. You'd think that mentally it'd be 
// really easy to disregard the comments, but in actual usage, it's a lot harder
// than a one Word answer that can tell you what you're looking for. It's tough.
/* Sometimes they'll even through you off with different comments. */ Yes.
// It's really tough to deal with people that don't like to use source control, 
// that would rather comment lines and lines of code instead of deleting the 
// code and checking in revision.  Cue irrelevant paragraph about the reason why 
// I wrote this instead of just deleting the entire block and replacing it 
// with my intention. Maybe I was hedging my bets? Cue misspelled wrod.  
18
George Stocker

Saya pikir perbedaan perlu dibuat antara kode komentar yang sudah usang, dan kode yang hanya digunakan dalam membangun debug (atau build "khusus" lainnya, dikompilasi dalam kondisi kondisional). Yang terakhir adalah praktik umum, dan tidak ada yang salah dengan itu.

Yang pertama tidak boleh ada di basis sumber, karena sistem kontrol versi melacak hal-hal yang usang, jika Anda ingin mendapatkannya kembali.

15
Alex Budovski

Hampir tidak ada "selalu" dalam coding :) Jika Anda cukup tahu tentang alasan di balik pedoman dan memiliki alasan yang sangat baik untuk melanggar itu, maka lakukanlah.

Sebagai contoh, saya berkomentar kode ketika saya melakukan "kamikaze-refactoring" dan perlu pengingat visual untuk menambahkan kembali atau mengingat bagaimana kode lama bekerja untuk sementara waktu. Sangat penting dalam kasus seperti ini bahwa Anda akan menghapus komentar di kemudian hari meskipun sebaliknya mereka hanya akan mengacaukan kode Anda.

11
Homde

Kadang-kadang Anda memasukkan kode ke komentar Anda untuk ditampilkan cara menggunakan kelas - ini sangat berbeda dari kode komentar keluar yang digunakan untuk menjalankan.

8
Ian

Saya melakukan banyak ulasan kode dan saya menemukan tidak ada alasan nyata untuk kode komentar terlepas dari alasannya. Jika Anda menggunakan kode yang dikomentari untuk tujuan debugging Anda dapat membuat mekanisme jejak yang dinonaktifkan dalam mode rilis atau memiliki tingkat pelacakan (selalu baik untuk dapat dilacak dalam versi rilis) atau Anda dapat menggunakan debugger.

Kode yang dikomentari adalah buruk karena ketika orang lain membaca kode - terutama ketika Anda sedang stres mencoba untuk memperbaiki bug ketika penulis asli sedang pergi berlibur - adalah bahwa itu sangat membingungkan untuk membaca kode, terutama jika kesalahannya dari kesalahan ditempatkan // di awal baris ... bahkan menggunakan/* Anda mungkin secara tidak sengaja berkomentar sesuatu yang seharusnya ada di sana - atau tidak.

Untuk menjaga kode Anda tetap bersih dan lebih mudah dibaca, hapus kode yang sudah dikomentari, programnya sudah sulit dibaca karena tanpa harus membaca kode yang mungkin atau mungkin tidak signifikan.

3
AndersK

Ya itu.

Meskipun Anda memiliki kode debug yang tidak Anda inginkan dalam rilis produksi Anda, Anda tidak perlu berkomentar. Menggunakan #ifdef lebih baik, karena dengan begitu Anda dapat menghidupkan dan mematikan debugging dengan mudah dengan #define makro, atau dengan memiliki konfigurasi bangunan terpisah. Ini pasti mengalahkan harus masuk ke kode dan berkomentar/menghapus komentar setiap blok kode debug secara manual.

Dan jika Anda perlu memiliki fleksibilitas untuk mengaktifkan beberapa blok debugging tetapi bukan yang lain, maka Anda harus mengelompokkan blok-blok debugging menjadi "level debug".

Solusi yang lebih baik adalah dengan tidak menggunakan pra-prosesor sama sekali, dan menggunakan fitur bahasa asli, seperti konstanta dan pernyataan-if. Jadi, bukannya

#define DEBUG0
#ifdef DEBUG0
  // debugging code
#endif

kamu bisa memiliki

const bool DEBUG0 = true;
if(DEBUG0)
{
  // debugging code
}

Keuntungan melakukan ini, daripada menggunakan pra-prosesor adalah bahwa kode debug Anda akan selalu diperiksa oleh kompiler. Ini mengurangi kemungkinan itu akan membusuk, ketika Anda mengubah kode di sekitarnya.

Anda tidak akan menderita hit performa apa pun jika Anda membuat boolean flag palsu, karena kompiler modern mengoptimalkan kode yang tidak dapat dijangkau. Paling buruk, Anda mungkin mendapatkan peringatan kompilator tentang hal itu.

2
Dima

Saya tidak berpikir apa yang Anda lakukan adalah keluar dan keluar buruk tapi saya pikir setidaknya Anda harus memiliki beberapa aktual komentar dengannya untuk menjelaskan apa yang dilakukannya, mengapa dan bagaimana dan kapan menggunakan Itu.

Secara pribadi saya biasanya meletakkan hal semacam ini di semacam IF DebugMode = usaha jenis TRUE di sekitar kode yang bersangkutan dan menetapkan itu sebagai baris perintah/memulai parameter. Bagi saya itu membuatnya lebih mudah untuk melihat bahwa itu sebabnya kode itu ada dan bagaimana mengaturnya meskipun dalam contoh Anda mungkin ada masalah kinerja bahkan dengan perbandingan kecil yang ingin Anda hindari.

Jadi saya mungkin akan melihat apa yang Anda lakukan sebagai kejahatan yang diperlukan daripada salah dan keluar. Jika Anda dapat menemukan cara untuk merampingkannya maka jelas melakukannya tetapi saya tidak akan menyalahkan diri sendiri tentang hal itu.

1
Jon Hopkins

Saya berpikir bahwa salah satu alasan yang berkomentar kode dianggap sebagai bau kode adalah bahwa hal itu menunjukkan bahwa programmer yang meletakkannya di sana tidak memahami kontrol sumber mereka atau bahwa mereka tidak menggunakan apapun. Entah dari mana yang menimbulkan keraguan lebih lanjut pada banyak hal lain yang mereka lakukan juga.

Jika Anda memiliki alasan yang sah untuk itu dan Anda meninggalkan penjelasan mengapa itu adalah alasan yang sah di mana dapat ditemukan Anda mungkin baik-baik saja. Sebagian besar hal yang umumnya dianggap sebagai berita buruk juga bisa menjadi alat yang berguna di tangan kanan. Masalahnya adalah tangan-tangan itu lebih jarang daripada orang yang berpikir mereka memilikinya.

0
glenatron

Ini membantu untuk memberikan sejarah tentang bagaimana pikiran programmer bekerja pada saat itu. Tetapi pada hari-hari ini dari mana-mana kontrol sumber tidak ada alasan untuk membiarkannya dalam pemotongan akhir - versi sebelumnya akan berisi kode yang lebih lama jika Anda perlu merujuknya.

0
5arx

Saya tidak berpikir ada yang absolut di sini. Terkadang saya meninggalkan kode yang dikomentari ketika itu hanya potongan kecil, terutama jika ada kesempatan yang masuk akal bahwa saya akan menghapus komentarnya lagi segera. Pada dasarnya saya meninggalkan potongan-potongan itu selama tidak mengganggu keterbacaan kode aktual, dan selama mereka tidak berlipat ganda di mana-mana.

Yang benar-benar saya tolak adalah metode lengkap untuk kode yang dikomentari. Ya, saya pernah melihat itu sebelumnya: WTF. Mereka dapat beristirahat di surga revisi sumber ;-)

0
Andres F.