Kutipan Robert C. Martin diambil di luar konteks. Berikut ini kutipan dengan konteks yang sedikit lebih banyak:
Tidak ada yang bisa sangat membantu sebagai komentar yang ditempatkan dengan baik. Tidak ada yang dapat mengacaukan modul lebih dari komentar dogmatis sembrono. Tidak ada yang bisa begitu merusak seperti komentar crufty tua yang menyebarkan kebohongan dan informasi yang salah.
Komentar tidak seperti Daftar Schindler. Mereka bukan "murni baik." Memang, komentar, paling tidak, adalah kejahatan yang perlu. Jika bahasa pemrograman kami cukup ekspresif, atau jika kami memiliki bakat untuk menggunakan bahasa tersebut secara halus untuk mengekspresikan niat kami, kami tidak akan terlalu membutuhkan komentar - mungkin tidak sama sekali.
Penggunaan komentar yang tepat adalah untuk mengkompensasi kegagalan kami untuk mengekspresikan diri dalam kode. Perhatikan bahwa saya menggunakan kata gagal. Aku serius. Komentar selalu gagal. Kita harus memilikinya karena kita tidak bisa selalu mencari cara untuk mengekspresikan diri tanpa mereka, tetapi penggunaannya bukan merupakan alasan untuk perayaan.
Jadi ketika Anda menemukan diri Anda dalam posisi di mana Anda perlu menulis komentar, pikirkan itu dan lihat apakah tidak ada cara untuk membalik tabel dan mengekspresikan diri Anda dalam kode. Setiap kali Anda mengekspresikan diri dalam kode, Anda harus menepuk punggung Anda. Setiap kali Anda menulis komentar, Anda harus meringis dan merasakan kegagalan kemampuan berekspresi Anda.
(Disalin dari sini , tetapi kutipan asli dari Clean Code: A Handbook of Agile Software Craftsmanship )
Bagaimana kutipan ini direduksi menjadi "Komentar selalu gagal" adalah contoh yang baik tentang bagaimana beberapa orang akan mengambil kutipan yang masuk akal dari konteks dan mengubahnya menjadi dogma bodoh.
Dokumentasi API (seperti javadoc) seharusnya mendokumentasikan API sehingga pengguna dapat menggunakannya tanpa harus membaca kode sumber . Jadi dalam hal ini dokumentasi harus menjelaskan apa metode ini. Sekarang Anda dapat berargumen bahwa "Mengambil produk dengan id-nya" berlebihan karena sudah ditunjukkan oleh nama metode, tetapi informasi yang null
dapat dikembalikan pasti penting untuk didokumentasikan, karena ini tidak dengan cara apa pun yang jelas.
Jika Anda ingin menghindari perlunya komentar, Anda harus menghapus masalah mendasar (yang merupakan penggunaan null
sebagai nilai pengembalian yang valid), dengan membuat API lebih eksplisit. Misalnya Anda dapat mengembalikan beberapa jenis Option<Product>
, jadi tanda tangan jenis itu sendiri mengkomunikasikan dengan jelas apa yang akan dikembalikan jika produk tidak ditemukan.
Tetapi bagaimanapun juga tidak realistis untuk mendokumentasikan API sepenuhnya hanya melalui nama metode dan tipe tanda tangan. Gunakan komentar dokumen untuk informasi tambahan yang tidak jelas yang harus diketahui pengguna. Ambil katakan dokumentasi API dari DateTime.AddMonths()
dalam BCL:
Metode AddMonths menghitung bulan dan tahun yang dihasilkan, dengan mempertimbangkan tahun kabisat dan jumlah hari dalam sebulan, kemudian menyesuaikan bagian hari dari objek DateTime yang dihasilkan. Jika hari yang dihasilkan bukan hari yang valid di bulan yang dihasilkan, hari valid terakhir dari bulan yang dihasilkan digunakan. Misalnya, 31 Maret + 1 bulan = 30 April. Bagian waktu-hari dari objek DateTime yang dihasilkan tetap sama dengan instance ini.
Tidak mungkin Anda bisa mengungkapkan ini hanya dengan menggunakan nama metode dan tanda tangan! Tentu saja dokumentasi kelas Anda mungkin tidak memerlukan tingkat detail ini, itu hanya sebuah contoh.
Komentar sebaris juga tidak buruk.
Bad komentar buruk. Misalnya komentar yang hanya menjelaskan apa yang bisa dilihat sepele dari kode, contoh klasiknya adalah:
// increment x by one
x++;
Komentar yang menjelaskan sesuatu yang dapat dibuat jelas dengan mengganti nama variabel atau metode atau merestrukturisasi kode, adalah bau kode:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
Ini adalah jenis komentar yang menentang Martin. Komentar adalah gejala kegagalan menulis kode yang jelas - dalam hal ini menggunakan nama yang jelas untuk variabel dan metode. Komentar itu sendiri tentu saja bukan masalahnya, masalahnya adalah kita perlu komentar untuk memahami kode.
Tetapi komentar harus digunakan untuk menjelaskan segala sesuatu yang tidak jelas dari kode, misalnya mengapa kode ditulis dengan cara yang tidak jelas:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
Komentar yang menjelaskan apa yang dilakukan sepotong kode yang terlalu berbelit-belit juga merupakan bau, tetapi perbaikannya bukan untuk melarang komentar, perbaikannya adalah memperbaiki kodenya! Dengan kata lain, kode berbelit-belit memang terjadi (semoga hanya sementara sampai refactor) tetapi tidak ada pengembang biasa yang menulis kode bersih sempurna pertama kali. Ketika kode berbelit-belit terjadi, jauh lebih baik menulis komentar yang menjelaskan apa yang dilakukannya daripada tidak menulis komentar. Komentar ini juga akan memudahkan refactor nanti.
Terkadang kode tidak dapat dihindari kompleks. Ini mungkin algoritma yang rumit, atau mungkin kode yang mengorbankan kejelasan untuk alasan kinerja. Sekali lagi komentar diperlukan.