Mengomentari kode dalam lingkungan pemrograman sering dianggap sebagai pemborosan waktu atau sinyal bahwa kode tersebut dapat diperbaiki. Berikut kutipan dari file CONTRIBUTING.md yang saya temukan di GitHub (dan ada banyak contohnya):
Komentar harus dihindari. Jika kode Anda tidak dapat dipahami tanpa komentar, tulis ulang untuk menjelaskannya sendiri.
Saya percaya bahwa dalam banyak kasus, nasihat seperti itu tidak akan berhasil dan tidak benar. Saya percaya pendekatan ini berakar pada pengalaman belajar kebanyakan orang yang telah mempelajari pemrograman. Ketika saya belajar ilmu komputer di universitas (meskipun nasehat ini bisa ditemukan di banyak mata kuliah, belum tentu di universitas), saya sangat ingat seorang guru di semester pertama yang mengatakan:
Setiap baris kode harus memiliki komentar yang menjelaskan fungsinya. Pekerjaan Anda dalam kursus akan dinilai berdasarkan kriteria ini.
Jadi, katakanlah Anda adalah siswa yang baru matang yang baru memulai kursus ini. Apa yang akan kamu lakukan? Komentari kodenya, tentu saja!
// bar
const inputValue = process.ENV.bar
// 2
const newValue = inputValue * 2
// square
const finalValue = square(newValue)
//
const square = (x) => x * xOrang yang mengatakan komentar itu buruk sebenarnya memikirkan komentar seperti ini. Dan mereka memang benar! Komentar seperti di atas yang menjawab pertanyaan “bagaimana?” Dalam pemrograman sama sekali tidak berguna. Semua komentar ini tidak menambahkan apa pun ke kode yang tidak dapat dipahami dari kode itu sendiri.
Jawab pertanyaan "mengapa?"
Masalah dengan komentar di atas adalah mereka menjelaskan caranya . Menjelaskan langkah-langkah yang kami ambil dalam kode. Komentar seperti itu jarang membantu; kode itu sendiri jauh lebih baik dalam memberi tahu Anda apa yang harus dilakukan. Bagaimanapun, baris kode hanyalah instruksi yang memberi tahu komputer cara menyelesaikan tugas.
Biasanya, tidak perlu banyak komentar, karena Anda dapat menulis kode sederhana tanpa fitur atau nuansa yang akan memberikan tampilan yang tidak dapat dipahami. Tetapi terkadang situasi muncul ketika tidak mungkin untuk menulis kode dasar dan intuitif. Mungkin itu bug yang harus Anda atasi. Atau Anda mewarisi kebahagiaan dari pengembang sebelumnya dalam bentuk sistem yang tidak memungkinkan Anda menyelesaikan masalah dengan cara yang Anda inginkan. Atau, pada akhirnya, tidak ada cara mudah untuk meningkatkan kode Anda.
Pernah saya bekerja di perusahaan pengolahan. Setiap hari kami menjalankan kueri SQL besar yang memilih pembayaran untuk dibayar. Kueri telah dioptimalkan dengan baik - kami membutuhkannya sangat cepat - dan sangat kompleks pada saat itu: kami harus mempertimbangkan banyak kasus edge. Kami berusaha sangat keras untuk membuatnya sejelas mungkin. Namun, permintaan ini tidak pernah bisa sepenuhnya intuitif dan mudah dimengerti. Itu hanya berisi terlalu banyak kode dengan sekumpulan kondisi dan logika yang hanya dapat dipahami dalam konteks perusahaan kami dan cara kerjanya.
Saya ingin menemukan contoh untuk ditampilkan di sini, jadi saya pergi ke belantara basis kode React untuk menemukan sesuatu. Anda tidak perlu menjadi pengembang React untuk mengetahuinya. Jadi, inilah kode yang ingin saya soroti:
// key . ,
// key (, <div {...props} key="Hi" />
// <div key="Hi" {...props} /> ). key, ,
// jsxDEV ,
// <div {...props} key="Hi" />, ,
// key .
if (maybeKey !== undefined) {
key = '' + maybeKey
}( Dan ini adalah tautannya di GitHub ).
Perhatikan kode itu sendiri:
if (maybeKey !== undefined) {
key = '' + maybeKey
}Tidak sulit untuk mengetahui apa yang dilakukannya. Jika maybeKey tidak ditentukan, kami menetapkan nilai maybeKey yang dirangkai ke kunci. Catatan: Ini adalah sedikit trik JavaScript untuk
'' + maybeKeymengubah konten maybeKey menjadi string.
Tapi di sini pertanyaan utamanya adalah tentang mengapa . Komentar untuk kode ini bagus. Dia menunjukkan masalahnya, memberikan dua contoh, dan juga menjelaskan bagaimana menyelesaikan masalah ini dalam jangka panjang dan apa yang kita lakukan dalam jangka pendek.
Jika Anda ingin melihat komentar yang saya tinggalkan di kode yang saya tulis, ini dia (TypeScript / Closure Compiler) . Ini adalah contoh yang baik dari jenis komentar yang menurut saya sangat berharga.
Pada akhirnya, kode apa pun bisa dipahami. Bagaimanapun, kode tidak lebih dari instruksi yang memberi tahu komputer cara melanjutkan. Kode ini bisa membingungkan, tetapi tidak bisa berbohong; jika waktu cukup, setiap pengembang dapat mempelajari kode langkah demi langkah dan memahami apa yang dilakukannya. Terkadang jauh lebih sulit untuk memahami mengapa dia melakukannya. Jadi biarkan rekan kerja Anda (atau diri Anda di masa depan dalam enam bulan) sedikit konteks tentang mengapa dan untuk apa kode Anda melakukan apa yang dilakukannya. Akan jauh lebih baik.