Memahami Kod Bersih: Komen ⚡️

Komen kod dianggap perlu dalam pembangunan perisian, tetapi buku Kod Bersih mencadangkan bahawa kod harus jelas tanpa memerlukan ulasan.

Kami akan meneroka masa untuk menggunakan ulasan, masa untuk mengelakkannya dan cara menulis ulasan berharga dalam kod JavaScript.

---

?Bila Mengelakkan Komen

1. Kod Jelas:

Ulasan tidak boleh digunakan untuk menerangkan perkara yang dilakukan oleh kod jika ia sudah jelas daripada kod itu sendiri.

Contohnya:

// Increment the counter by 1
counter++;

// Check if the user is an admin
if (user.isAdmin()) {
    // ...
}

Dalam kes ini, ulasan adalah berlebihan kerana kod itu menerangkan sendiri. Daripada menambah ulasan yang tidak perlu, tumpukan pada menjadikan kod anda lebih mudah dibaca.

2. Komen Mengelirukan:

Ulasan yang tidak sepadan dengan kod boleh menyebabkan kekeliruan dan ralat. Jika anda mengemas kini kod tetapi terlupa untuk mengemas kini ulasan, ia menjadi mengelirukan:

// Initialize user object
let user = new AdminUser(); // Actually, it's creating an AdminUser, not a regular user

Di sini, ulasan itu mengelirukan dan boleh mengelirukan seseorang yang membaca kod itu nanti. Lebih baik sama ada mengalih keluar ulasan atau memastikan ia menggambarkan kod dengan tepat.

3. Kod Diulas Keluar:

Membiarkan kod lama diulas adalah amalan buruk yang biasa. Ia mengacaukan pangkalan kod dan boleh mengelirukan:

// Old code
// let data = fetchDataFromAPI();

// New code
let data = fetchDataFromDatabase();

Daripada meninggalkan kod lama diulas, gunakan sistem kawalan versi seperti Git untuk menjejaki perubahan kod. Ini memastikan pangkalan kod anda bersih dan fokus.

---

---

? Bila Menggunakan Komen

1. Menjelaskan Niat:

Jika sekeping kod mempunyai logik yang kompleks atau melibatkan penyelesaian, ulasan boleh menjelaskan sebab kod itu wujud:

// Using a workaround for browser-specific bug in IE11
if (isIE11()) {
    fixIEBug();
}

Ulasan menerangkan sebab kod itu perlu, memberikan konteks yang berharga kepada pembangun masa hadapan.

2. Maklumat Undang-undang:

Kadangkala, ulasan diperlukan atas sebab undang-undang, seperti memasukkan maklumat hak cipta atau butiran pelesenan:

/*
 * Copyright (c) 2024 MyCompany. All rights reserved.
 * Licensed under the MIT License.
 */

Komen ini penting dan harus disertakan seperti yang diperlukan oleh pelesenan projek anda.

3. Penjelasan Keputusan:

Apabila keputusan khusus dalam kod memerlukan justifikasi, ulasan boleh membantu:

// Using a binary search because the list is sorted
let index = binarySearch(sortedArray, target);

Ulasan ini menerangkan sebab carian binari dipilih, memberikan cerapan tentang alasan di sebalik pelaksanaan.

4. API Awam:

Apabila menulis API yang menghadap awam, ulasan boleh membantu mendokumenkan cara menggunakannya, terutamanya dalam JavaScript yang anda mungkin tidak mempunyai alat dokumentasi terbina dalam:

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateArea(width, height) {
    return width * height;
}

Dalam kes ini, ulasan menyediakan dokumentasi yang jelas tentang cara menggunakan fungsi tersebut, yang amat berguna untuk pembangun lain yang mungkin menggunakannya.

---

---

? Menulis Komen Berguna

• Jelas dan Ringkas: Komen hendaklah berterus-terang dan pada intinya. Elakkan daripada menulis penjelasan panjang lebar yang boleh difahami dengan mudah daripada kod itu sendiri.

• Elak Jargon: Gunakan bahasa yang mudah difahami, elakkan jargon teknikal yang mungkin tidak biasa kepada semua orang yang membaca kod.

• Kemas kini Komen: Sentiasa kemas kini ulasan anda apabila kod berubah. Peraturan praktikal yang baik ialah: jika anda menyentuh kod, semak ulasan.

• Fokus pada Mengapa, Bukan Apa: Komen yang baik menerangkan sebab keputusan tertentu dibuat dan bukannya menerangkan perkara yang dilakukan oleh kod itu:
  

// We need to sort the array before performing the search
array.sort();

Ulasan ini menerangkan sebab pengisihan perlu sebelum carian, menambah konteks yang berharga.

---

---

Kesimpulan ✅

Walaupun ulasan boleh membantu, Kod Bersih mengajar kita bahawa ia harus digunakan dengan berhati-hati dan bertujuan.

Matlamatnya adalah untuk menulis kod yang begitu jelas sehingga ulasan menjadi hampir tidak diperlukan.

Apabila ulasan diperlukan, pastikan ia bermakna dan tepat serta berikan nilai kepada sesiapa yang membaca kod anda.

Dengan mengikuti garis panduan ini, anda bukan sahaja akan meningkatkan kualiti kod anda tetapi juga memudahkan orang lain (dan diri masa depan anda) untuk memahami dan mengekalkannya.

Selamat mengekod!

Atas ialah kandungan terperinci Memahami Kod Bersih: Komen ⚡️. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!