Seorang rekan kerja saya percaya bahwa setiap penggunaan komentar dalam kode (yaitu, bukan metode gaya javadoc atau komentar kelas) adalah bau kode . Bagaimana menurut anda?
comments
anti-patterns
Fishtoaster
sumber
sumber
Jawaban:
Hanya jika komentar menjelaskan apa yang dilakukan kode.
Jika saya ingin tahu apa yang terjadi dalam suatu metode atau blok, saya akan membaca kodenya. Saya berharap, bagaimanapun, bahwa setiap pengembang yang mengerjakan proyek tertentu setidaknya cukup akrab dengan bahasa pengembangan untuk membaca apa yang ditulis dan memahami apa yang dilakukannya.
Dalam beberapa kasus optimisasi ekstrem, Anda mungkin menggunakan teknik yang menyulitkan seseorang untuk mengikuti apa yang dilakukan kode Anda. Dalam kasus ini, komentar dapat dan harus digunakan untuk tidak hanya menjelaskan mengapa Anda memiliki optimasi seperti itu, tetapi apa yang dilakukan kode. Aturan praktis yang baik adalah meminta orang lain (atau banyak orang lain) akrab dengan bahasa implementasi dan proyek melihat kode Anda - jika mereka tidak dapat memahami mengapa dan bagaimana, maka Anda harus mengomentari mengapa dan bagaimana caranya.
Namun, yang tidak jelas dalam kode adalah mengapa Anda melakukan sesuatu. Jika Anda mengambil pendekatan yang mungkin tidak jelas bagi orang lain, Anda harus memiliki komentar yang menjelaskan mengapa Anda membuat keputusan yang Anda lakukan. Saya akan curiga bahwa Anda mungkin bahkan tidak menyadari bahwa komentar diperlukan sampai setelah sesuatu seperti tinjauan kode, di mana orang ingin tahu mengapa Anda melakukan X daripada Y - Anda dapat menangkap jawaban Anda dalam kode untuk semua orang yang melihatnya di masa depan.
Namun, hal yang paling penting adalah mengubah komentar Anda ketika Anda mengubah kode Anda. Jika Anda mengubah algoritme, pastikan untuk memperbarui komentar dengan alasan Anda menggunakan algoritme X lebih dari Y. Komentar basi adalah bau kode yang lebih besar.
sumber
Ini sangat menjengkelkan untuk didengar saat ini, saya menghabiskan waktu akhir pekan ini untuk melihat kode yang sangat terkenal, sangat bersih, tidak diomentari yang mengimplementasikan algoritma penelitian (yang tidak benar-benar dipublikasikan). Saya sangat akrab dengannya, orang yang duduk di sebelah saya adalah penemunya, dan kode itu ditulis beberapa tahun yang lalu oleh orang lain. Kami hampir tidak bisa mengikutinya.
Rekan kerja Anda tidak cukup berpengalaman, jelas.
sumber
Komentar harus menjelaskan mengapa, bukan bagaimana.
How
ketik komentar biasanya lebih baik ditangani dengan menggunakan refactoring. Secara pribadi, saya biasanya menghindari komentar yang mendukung refactoring.Sebelum:
setelah:
sumber
Saya menyatakan rekan kerja Anda sesat! Di mana sepatu bot pembakaran sesat saya?
Komentar obsesif itu buruk dan sakit kepala, dan komentar bukan pengganti metode, kelas, variabel, dll. Namun, kadang-kadang mengatakan mengapa sesuatu itu bisa sangat berharga bagi idiot miskin yang harus menjaga kode dalam enam bulan - terutama ketika si idiot itu berakhir jadi Anda.
Beberapa komentar aktual dari kode yang saya kerjakan:
sumber
SomebodyScrewedAroundWithDatabaseException
...Idealnya, kode harus dikodekan dengan sangat baik sehingga harus bersifat eksplikatif otomatis. Di dunia nyata, kita tahu bahwa kebutuhan kode juga sangat tinggi terkadang perlu dikomentari.
Yang harus Anda hindari adalah "redundansi kode komentar" (komentar yang tidak menambahkan apa pun ke kode):
Kemudian, jika ada desain dan dokumentasi kode yang baik (dan dikelola / disejajarkan), berkomentar bahkan lebih tidak berguna.
Namun dalam beberapa keadaan komentar dapat menjadi bantuan yang baik dalam pembacaan kode:
Jangan lupa bahwa Anda harus menjaga dan tetap sinkron juga komentar ... komentar yang ketinggalan jaman atau salah bisa sangat menyebalkan! Dan, sebagai aturan umum, berkomentar terlalu banyak bisa menjadi gejala pemrograman yang buruk.
sumber
} //end while
hanya berarti awal dari loop sementara begitu jauh, Anda bahkan tidak bisa melihatnya, dan tidak ada petunjuk bahwa kode yang Anda lihat adalah dalam satu lingkaran. Refactoring berat harus lebih disukai daripada komentar tentang bagaimana kode terstruktur.} // end while
comments dapat menjadi penyelamat.Mendefinisikan secara kategoris suatu metode atau proses sebagai "bau kode" adalah "bau fanatik". Istilah ini menjadi baru "dianggap berbahaya".
Harap ingat bahwa semua hal ini seharusnya menjadi pedoman.
Banyak dari jawaban lain memberikan nasihat yang baik tentang kapan komentar dibenarkan.
Secara pribadi saya menggunakan sangat sedikit komentar. Jelaskan tujuan dari proses yang tidak jelas dan serahkan ancaman kematian sesekali kepada siapa pun yang mungkin mempertimbangkan untuk mengubah hal-hal sendiri yang membutuhkan penyetelan berminggu-minggu.
Refactoring semuanya sampai anak TK dapat memahaminya sepertinya bukan penggunaan waktu Anda secara efisien, dan mungkin tidak akan berkinerja sebaik versi yang lebih ringkas.
Komentar tidak memengaruhi waktu proses, jadi satu-satunya masalah negatif yang perlu dipertimbangkan adalah pemeliharaan.
sumber
Dalam beberapa kasus, tidak ada jumlah penamaan yang baik, refactoring dll dapat menggantikan komentar. Lihat saja contoh dunia nyata ini (bahasa adalah Groovy):
Terlihat aneh, bukan? Mungkin kesalahan salin-tempel? Menangis untuk perbaikan bug?
Sekarang sama dengan komentar:
sumber
Masalah utama di sini adalah arti dari istilah "bau kode".
Banyak orang (termasuk Anda, saya kira) memahami bau kode sebagai sesuatu yang dekat dengan kesalahan atau setidaknya sesuatu yang perlu diperbaiki. Mungkin Anda menganggapnya sebagai sinonim dengan "anti-pola".
Ini bukan arti dari istilah itu!
Metafora kode bau berasal dari Wards Wiki , dan mereka menekankan:
Jadi apa artinya komentar adalah bau kode: artinya ketika Anda melihat komentar, Anda harus berhenti sejenak dan berpikir: "Hmmm, saya merasakan petunjuk bahwa sesuatu dapat ditingkatkan". Mungkin Anda dapat mengubah nama variabel, melakukan "ekstrak metode" -mengevaluasi - atau mungkin komentar itu sebenarnya solusi terbaik.
Itulah artinya komentar menjadi bau kode.
EDIT: Saya baru saja meneliti dua artikel ini, yang menjelaskannya lebih baik daripada saya:
sumber
Saya pikir aturannya cukup sederhana: bayangkan orang asing melihat kode Anda. Anda mungkin akan menjadi orang asing dengan kode Anda sendiri dalam 5 tahun. Cobalah untuk meminimalkan upaya mental untuk memahami kode Anda untuk orang asing ini.
sumber
Ide yang bagus untuk mendapatkan komentar yang tepat adalah memulai dengan menulis komentar.
Ini memungkinkan Anda untuk mengekstrak metode dengan mudah bahkan untuk menghilangkan komentar,
biarkan saja kodenya memberitahukan hal-hal ini ! Lihat bagaimana ini ditulis ulang (potong / rekat) dengan cara yang sangat bagus:
Untuk hal-hal yang tidak dapat dipisahkan, jangan mengekstrak metode dan ketik kode di bawah komentar.
Inilah yang saya lihat sebagai cara yang berguna untuk terus mengomentari seminimal mungkin, tidak ada gunanya untuk mengomentari setiap baris ... Hanya mendokumentasikan satu baris jika ini tentang inisialisasi nilai magis atau di mana masuk akal.
Jika parameter terlalu banyak digunakan, maka itu haruslah anggota pribadi di kelas Anda.
sumber
Saya pikir jawabannya adalah yang biasa "Itu tergantung" satu. Mengomentari kode hanya untuk kode komentar adalah bau. Mengomentari kode karena Anda menggunakan algoritma yang tidak jelas yang merupakan urutan besarnya lebih cepat menyelamatkan programmer pemeliharaan (biasanya saya 6 bulan setelah saya menulisnya) setengah hari menyodok kode untuk menentukan apa yang dilakukannya.
sumber
atau
sumber
Komentar kode jelas bukan "bau kode". Keyakinan ini biasanya berasal dari fakta bahwa komentar dapat menjadi basi (ketinggalan zaman) dan dapat sulit dipertahankan. Namun, memiliki komentar yang baik yang menjelaskan mengapa kode melakukan sesuatu dengan cara tertentu dapat (dan biasanya) penting untuk pemeliharaan.
sumber
Jika kode telah ditulis dengan cara tertentu untuk menghindari masalah yang ada di perpustakaan (baik perpustakaan pihak ketiga, atau perpustakaan yang disertakan dengan kompiler), maka masuk akal untuk berkomentar.
Juga masuk akal untuk mengomentari kode yang perlu diubah di versi masa depan, atau ketika menggunakan versi baru perpustakaan, atau ketika meneruskan dari PHP4 ke PHP5, misalnya.
sumber
Bahkan buku yang paling ditulis dengan baik masih memiliki judul pengantar dan bab. Komentar dalam kode yang terdokumentasi dengan baik masih berguna untuk menggambarkan konsep tingkat tinggi, dan menjelaskan bagaimana kode tersebut disusun.
sumber
Yang terhormat disebutkan adalah anti-pola:
Ini kesan saya bahwa kadang-kadang contoh lisensi FLOSS sering digunakan sebagai pengganti dokumentasi file. GPL / BSDL membuat teks pengisi yang bagus, dan setelah itu Anda jarang melihat blok komentar lainnya.
sumber
Saya tidak setuju dengan gagasan bahwa menulis komentar untuk menjelaskan kode itu buruk. Ini sepenuhnya mengabaikan fakta bahwa kode memiliki bug. Mungkin jelas apa kode tidak tanpa komentar. Sepertinya tidak terlalu jelas apa yang seharusnya dilakukan oleh kode . Tanpa komentar bagaimana Anda tahu jika hasilnya salah, atau mereka digunakan secara tidak benar?
Komentar harus menjelaskan maksud kode, sehingga jika ada kesalahan, seseorang yang membaca kode komentar + memiliki peluang untuk menemukannya.
Saya biasanya menemukan diri saya menulis komentar sebaris sebelum saya menulis kode. Dengan cara ini jelas apa yang saya coba tulis kode untuk dilakukan, dan mengurangi tersesat dalam suatu algoritma tanpa benar-benar tahu apa yang Anda coba lakukan.
sumber
Komentar yang dimasukkan karena seseorang berpikir itu boleh saja memiliki 700 baris dalam satu metode adalah bau.
Komentar yang ada karena Anda tahu jika Anda tidak memberikan komentar, seseorang akan membuat kesalahan yang sama lagi-lagi bau.
Komentar dimasukkan karena beberapa alat analisis kode menuntutnya juga bau.
Orang-orang yang tidak akan pernah memberikan komentar, atau bahkan menulis sedikit bantuan untuk pengembang lain juga tidak enak. Saya kagum pada berapa banyak orang yang tidak akan menulis, tetapi kemudian akan berbalik dan mengakui bahwa mereka tidak dapat mengingat apa yang mereka lakukan 3 bulan lalu. Saya tidak suka menulis dokumen, tetapi saya harus memberi tahu orang hal yang sama berulang-ulang bahkan lebih sedikit.
sumber
Saya akan menjawab dengan pertanyaan saya sendiri. Dapatkah Anda menemukan bug dalam kode uncommented di bawah ini?
tl; dr: Orang berikutnya yang menjaga kode Anda mungkin tidak seperti dewa.
sumber
Anda harus menjaga keseimbangan antara kode dan komentar ... Biasanya saya mencoba menambahkan beberapa komentar yang melanjutkan satu blok kode. Bukan karena saya tidak akan dapat memahami kode (well, itu juga), tetapi karena saya dapat membaca lebih cepat kode saya sendiri dan menemukan bagian tertentu di mana hal-hal penting itu terjadi.
Bagaimanapun, kriteria pribadi saya sendiri adalah "ketika ragu, berkomentar". Saya lebih suka memiliki garis redundan daripada garis yang sepenuhnya samar yang saya tidak akan bisa mengerti. Saya selalu dapat menghapus komentar pada ulasan kode, setelah beberapa saat (dan biasanya saya lakukan)
Juga, komentar cukup membantu menambahkan "peringatan" seperti "Hati-hati! Jika format input bukan ASCII, kode ini harus diubah!"
sumber
Membaca ini saya teringat pada sesuatu yang pertama kali saya baca (dari daftar yang lebih panjang, diawetkan dengan mengambil fotokopi) beberapa dekade yang lalu:
Bau yang agak lebih tua.
sumber
Saya pikir komentar kode mendapat awal yang sangat buruk untuk hidup. Saya tidak tahu tentang hari-hari ini, tetapi ketika saya pertama kali diajarkan pemrograman di sekolah saya mendapat tugas dari sifat "Menulis program yang mencetak angka satu hingga sepuluh pada baris yang terpisah. Pastikan Anda mengomentari kode Anda." Anda akan ditandai jika Anda tidak menambahkan komentar karena mengomentari kode Anda adalah HAL YANG BAIK.
Tapi apa yang bisa dikatakan tentang proses sepele seperti itu? Jadi Anda akhirnya menulis klasik
hanya untuk mendapatkan nilai yang layak dan, jika Anda punya nous sama sekali, langsung membentuk pendapat komentar kode yang sangat rendah.
Mengomentari kode bukanlah HAL YANG BAIK. Ini hal yang perlu diperhatikan, dan Thomas Owens dalam jawaban teratas memberikan penjelasan yang sangat baik tentang situasi di mana itu perlu. Namun, situasi ini jarang muncul dalam penugasan jenis pekerjaan rumah.
Dalam banyak hal, menambahkan komentar harus dianggap sebagai pilihan terakhir, ketika apa yang perlu dikatakan tidak dapat dikatakan dengan jelas di bagian aktif dari bahasa pemrograman. Meskipun penamaan objek bisa basi, berbagai mekanisme manusia dan komputer kurang umpan balik membuatnya mudah untuk melupakan untuk menjaga komentar dan akibatnya komentar menjadi basi lebih cepat daripada kode aktif. Karena alasan itu, di mana suatu pilihan dimungkinkan, mengubah kode untuk membuatnya lebih jelas harus selalu lebih disukai daripada menjelaskan kode yang tidak jelas dengan komentar.
sumber
Tentu saja komentar adalah bau kode ...
setiap programmer tahu kita semua pada akhirnya menjadi gila karena jumlah pekerjaan, debugging, atau sekadar kegilaan yang kita alami.
"Melakukan hal ini!" kata manajer proyek Anda.
Anda menjawab, "Itu tidak bisa dilakukan."
Mereka berkata, "Kalau begitu kita akan menemukan orang lain untuk melakukannya."
Anda berkata, "Oke, mungkin itu bisa dilakukan."
Dan kemudian menghabiskan jumlah X hari berikutnya .. minggu .. bulan .. mencoba untuk mencari tahu. Sepanjang proses, Anda akan mencoba dan gagal, dan mencoba dan gagal. Kita semua melakukan ini. Jawaban yang benar adalah ada dua jenis programmer, yang berkomentar dan yang tidak.
1) Mereka yang melakukannya membuat pekerjaan mereka lebih mudah dengan mendokumentasikan referensi di masa mendatang, mengomentari kegagalan rutin yang tidak berhasil (baunya tidak menghapus mereka setelah menemukan yang berfungsi.), Atau memecah kode dengan komentar memformat agar mudah membuatnya lebih mudah dibaca atau dimengerti. Serius, saya tidak bisa menyalahkan mereka. Tetapi pada akhirnya, mereka patah dan kemudian Anda memiliki ini:
// dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2) Mereka yang tidak berpura-pura menjadi pahlawan super, atau hidup di gua . Mereka hanya mengabaikan orang yang ceroboh terhadap orang lain, diri mereka sendiri, dan tidak peduli dengan kode itu, atau apa artinya itu nantinya.
Sekarang jangan salah paham .. variabel dan fungsi self-documenting dapat menghindari ini sepenuhnya .. dan percayalah, Anda tidak akan pernah bisa melakukan pembersihan kode yang cukup. Tetapi kebenaran sederhananya adalah selama Anda menyimpan cadangan, Anda SELALU dapat menghapus komentar.
sumber
Saya berpendapat bahwa tidak menggunakan beberapa komentar dalam kode Anda adalah bau kode. Sementara saya setuju bahwa kode harus mendokumentasikan diri sendiri sebanyak mungkin, Anda mencapai titik tertentu di mana Anda akan melihat kode yang tidak masuk akal terlepas dari seberapa baik kode tersebut ditulis. Saya telah melihat beberapa kode dalam aplikasi bisnis di mana komentarnya cukup wajib karena:
Juga, panduan gaya perusahaan mungkin memberi tahu Anda untuk melakukan sesuatu dengan cara tertentu - jika mereka mengatakan bahwa Anda harus memiliki komentar yang menguraikan apa yang dilakukan oleh blok kode dalam suatu fungsi, maka sertakan komentar tersebut.
sumber
Ada perbedaan mendasar yang besar antara komentar dan kode: komentar adalah cara bagi orang untuk menyampaikan ide kepada orang lain, sedangkan kode terutama ditujukan untuk komputer. Ada banyak aspek dalam "kode" yang juga hanya untuk manusia, seperti penamaan dan lekukan. Tetapi komentar ditulis khusus untuk manusia, oleh manusia.
Oleh karena itu, menulis komentar sama sulitnya dengan komunikasi manusia tertulis! Penulis harus memiliki konsepsi yang jelas tentang siapa penontonnya, dan jenis teks apa yang akan mereka butuhkan. Bagaimana Anda bisa tahu siapa yang akan membaca komentar Anda dalam sepuluh, dua puluh tahun? Bagaimana jika orang tersebut berasal dari budaya yang sama sekali berbeda? Dll. Saya harap semua orang mengerti ini.
Bahkan di dalam budaya homogen kecil tempat saya tinggal, sangat sulit untuk mengkomunikasikan ide kepada orang lain. Komunikasi manusia biasanya gagal, kecuali karena kecelakaan.
sumber
Saya harus setuju dengan rekan kerja Anda. Saya selalu mengatakan bahwa jika saya berkomentar kode saya, itu berarti bahwa saya khawatir bahwa saya tidak akan dapat menemukan kode saya sendiri di masa depan. Ini pertanda buruk.
Satu-satunya alasan saya menaburkan komentar ke dalam kode adalah untuk memanggil sesuatu yang tampaknya tidak masuk akal.
Komentar-komentar itu biasanya berupa sesuatu seperti:
atau
sumber
Pemberian komentar kode, jika berlaku, unit argumen fungsi dan pengembalian, struktur bidang, bahkan variabel lokal bisa sangat berguna. Ingat Pengorbit Mars!
sumber
Inilah aturan praktis saya:
sumber
Didik rekan kerja Anda tentang teknik Pemrograman Literate .
sumber
Tidak, komentar bukan bau kode, mereka hanya alat yang dapat disalahgunakan.
Contoh dari komentar yang baik :
// Aku pikir ini dalam cm. Investigasi lebih lanjut diperlukan!
// Ini cara cerdas untuk melakukan X
// Daftar dijamin tidak kosong di sini
sumber
Assert(list.IsEmpty)
?Assert(!list.isEmpty())
tidak persis kontrak seperti dalam komentar ketiga, tetapi hanya perilaku (yaitu "membuang IllegalArgumentException jika argumen kosong") yang harus diuji unit seperti logika program lainnya. Perhatikan perbedaan halus dengan komentar, yang menyatakan kapan metode dapat digunakan, tetapi menentukan tidak ada perilaku jika prasyarat tidak terpenuhi. Bahkan lebih baik daripada komentar adalah untuk menegakkan kontrak waktu kompilasi. Tapi ini melebihi ruang lingkup jawabanku;)Assert
, karena mereka menggambarkan hal-hal yang seharusnya tidak pernah terjadi, bahkan jika API publik menerima argumen yang tidak valid.