Seperti yang kita ketahui dari bab Struktur kode, komentar dapat berupa satu baris: dimulai dengan // dan multiline: /* ... */ .
Kami biasanya menggunakannya untuk menjelaskan bagaimana dan mengapa kode tersebut bekerja.
Pada pandangan pertama, berkomentar mungkin terlihat jelas, tetapi pemula dalam pemrograman sering kali salah menggunakannya.
Pemula cenderung menggunakan komentar untuk menjelaskan “apa yang terjadi dalam kode”. Seperti ini:
// Kode ini akan melakukan hal ini (...) dan hal itu (...) // ...dan entah apa lagi... sangat; kompleks; kode;
Namun dalam kode yang baik, jumlah komentar “penjelasan” tersebut harus minimal. Serius, kodenya seharusnya mudah dimengerti tanpanya.
Ada aturan bagus tentang itu: "jika kodenya sangat tidak jelas sehingga memerlukan komentar, mungkin kode tersebut harus ditulis ulang".
Terkadang bermanfaat untuk mengganti potongan kode dengan suatu fungsi, seperti di sini:
fungsi tampilkan bilangan prima(n) {
berikutnyaPerdana:
untuk (misalkan i = 2; i < n; i++) {
// periksa apakah i bilangan prima
untuk (misalkan j = 2; j < i; j++) {
jika (i % j == 0) lanjutkan nextPrime;
}
peringatan(i);
}
} Varian yang lebih baik, dengan fungsi yang difaktorkan isPrime :
fungsi tampilkan bilangan prima(n) {
untuk (misalkan i = 2; i < n; i++) {
jika (!isPrime(i)) lanjutkan;
peringatan(i);
}
}
fungsi isPrime(n) {
untuk (misalkan i = 2; i < n; i++) {
jika (n % i == 0) mengembalikan salah;
}
kembali benar;
}Sekarang kita dapat memahami kodenya dengan mudah. Fungsinya sendiri menjadi komentar. Kode seperti ini disebut deskriptif diri .
Dan jika kita memiliki “lembar kode” yang panjang seperti ini:
// di sini kita menambahkan wiski
untuk(misalkan i = 0; i < 10; i++) {
biarkan jatuhkan = getWhiskey();
bau(jatuhkan);
tambahkan(jatuhkan, gelas);
}
// di sini kita menambahkan jus
untuk(misalkan t = 0; t < 3; t++) {
biarkan tomat = getTomato();
memeriksa(tomat);
biarkan jus = tekan(tomat);
menambahkan(jus, gelas);
}
// ...Maka mungkin merupakan varian yang lebih baik untuk memfaktorkannya kembali menjadi fungsi-fungsi seperti:
tambahkanWhiskey(gelas);
tambahkanJus(gelas);
fungsi addWhiskey(wadah) {
untuk(misalkan i = 0; i < 10; i++) {
biarkan jatuhkan = getWhiskey();
//...
}
}
fungsi addJuice(wadah) {
untuk(misalkan t = 0; t < 3; t++) {
biarkan tomat = getTomato();
//...
}
}Sekali lagi, fungsi itu sendiri yang memberitahukan apa yang terjadi. Tidak ada yang perlu dikomentari. Dan juga struktur kodenya lebih baik jika dipecah. Jelas apa yang dilakukan setiap fungsi, apa yang diperlukan, dan apa yang dikembalikan.
Pada kenyataannya, kita tidak bisa sepenuhnya menghindari komentar yang “menjelaskan”. Ada algoritma yang kompleks. Dan ada “tweak” cerdas untuk tujuan optimasi. Namun secara umum kita harus mencoba untuk menjaga kode tetap sederhana dan deskriptif.
Jadi, komentar penjelasan biasanya buruk. Komentar mana yang bagus?
Jelaskan arsitekturnya
Berikan gambaran umum tingkat tinggi tentang komponen, bagaimana mereka berinteraksi, apa aliran kontrol dalam berbagai situasi… Singkatnya – kode secara sekilas. Ada bahasa khusus UML untuk membangun diagram arsitektur tingkat tinggi yang menjelaskan kodenya. Pasti layak untuk dipelajari.
Parameter fungsi dokumen dan penggunaannya
Ada sintaks khusus JSDoc untuk mendokumentasikan suatu fungsi: penggunaan, parameter, nilai yang dikembalikan.
Misalnya:
/**
* Mengembalikan x yang dipangkatkan ke-n.
*
* @param {number} x Jumlah yang akan dinaikkan.
* @param {angka} n Pangkatnya, harus bilangan asli.
* @return {number} x dipangkatkan ke-n.
*/
fungsi kekuatan(x, n) {
...
}Komentar seperti itu memungkinkan kita memahami tujuan fungsi dan menggunakannya dengan cara yang benar tanpa melihat kodenya.
Omong-omong, banyak editor seperti WebStorm juga dapat memahaminya dan menggunakannya untuk menyediakan pelengkapan otomatis dan beberapa pemeriksaan kode otomatis.
Juga, ada alat seperti JSDoc 3 yang dapat menghasilkan dokumentasi HTML dari komentar. Anda dapat membaca informasi lebih lanjut tentang JSDoc di https://jsdoc.app.
Mengapa tugas ini diselesaikan dengan cara ini?
Apa yang tertulis itu penting. Namun apa yang tidak tertulis mungkin lebih penting untuk memahami apa yang sedang terjadi. Mengapa masalahnya diselesaikan dengan cara ini? Kode tidak memberikan jawaban.
Jika ada banyak cara untuk menyelesaikan masalah, mengapa cara ini? Terutama jika itu bukan hal yang paling jelas.
Tanpa komentar seperti itu, situasi berikut mungkin terjadi:
Anda (atau kolega Anda) membuka kode yang ditulis beberapa waktu lalu, dan melihat bahwa kode tersebut “kurang optimal”.
Anda berpikir: “Betapa bodohnya saya saat itu, dan betapa lebih pintarnya saya sekarang”, dan menulis ulang menggunakan varian yang “lebih jelas dan benar”.
…Dorongan untuk menulis ulang itu bagus. Namun dalam prosesnya Anda melihat bahwa solusi yang “lebih jelas” sebenarnya masih kurang. Anda bahkan samar-samar mengingat alasannya, karena Anda sudah mencobanya sejak lama. Anda kembali ke varian yang benar, tetapi waktu terbuang percuma.
Komentar yang menjelaskan solusinya sangatlah penting. Mereka membantu melanjutkan pembangunan dengan cara yang benar.
Adakah fitur halus dari kode ini? Dimana mereka digunakan?
Jika kode tersebut memiliki sesuatu yang halus dan kontra-intuitif, itu pasti layak untuk dikomentari.
Tanda penting dari pengembang yang baik adalah komentar: kehadiran dan bahkan ketidakhadiran mereka.
Komentar yang baik memungkinkan kami memelihara kode dengan baik, kembali lagi setelah penundaan, dan menggunakannya dengan lebih efektif.
Beri komentar ini:
Arsitektur keseluruhan, tampilan tingkat tinggi.
Penggunaan fungsi.
Solusi penting, terutama bila tidak langsung terlihat.
Hindari komentar:
Itu menjelaskan “cara kerja kode” dan “apa fungsinya”.
Masukkan kode tersebut hanya jika tidak mungkin membuat kode menjadi begitu sederhana dan deskriptif sehingga tidak memerlukannya.
Komentar juga digunakan untuk alat dokumentasi otomatis seperti JSDoc3: mereka membacanya dan menghasilkan dokumen HTML (atau dokumen dalam format lain).