Understanding Clean Code: Comments ⚡️

Code comments are considered necessary in software development, but the Clean Code book suggests that code should be self-explanatory without needing comments.

We'll explore when to use comments, when to avoid them, and how to write valuable comments in JavaScript code.

---

?When to Avoid Comments

1. Obvious Code:

Comments should not be used to explain what the code is doing if it's already clear from the code itself.

For example:

// Increment the counter by 1
counter++;

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

In these cases, the comments are redundant because the code is self-explanatory. Instead of adding unnecessary comments, focus on making your code more readable.

2. Misleading Comments:

A comment that doesn't match the code can lead to confusion and errors. If you update the code but forget to update the comment, it becomes misleading:

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

Here, the comment is misleading and could confuse someone reading the code later. It’s better to either remove the comment or make sure it accurately reflects the code.

3. Commented-Out Code:

Leaving old code commented out is a common bad practice. It clutters the codebase and can confuse:

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

// New code
let data = fetchDataFromDatabase();

Instead of leaving old code commented out, use version control systems like Git to track code changes. This keeps your codebase clean and focused.

---

---

? When to Use Comments

1. Clarifying Intent:

If a piece of code has complex logic or involves a workaround, a comment can clarify why the code exists:

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

The comment explains why the code is necessary, providing valuable context to future developers.

2. Legal Information:

Sometimes, comments are necessary for legal reasons, such as including copyright information or licensing details:

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

These comments are essential and should be included as required by your project’s licensing.

3. Explanation of a Decision:

When a specific decision in the code needs justification, a comment can be helpful:

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

This comment explains why a binary search was chosen, providing insight into the reasoning behind the implementation.

4. Public APIs:

When writing public-facing APIs, comments can help document how to use them, especially in JavaScript where you might not have built-in documentation tools:

/**
 * 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;
}

In this case, the comment provides clear documentation on how to use the function, which is especially useful for other developers who might use it.

---

---

? Writing Helpful Comments

• Be Clear and Concise: Comments should be straightforward and to the point. Avoid writing long-winded explanations that could be easily understood from the code itself.

• Avoid Jargon: Use language that is easy to understand, avoiding technical jargon that might not be familiar to everyone reading the code.

• Update Comments: Always update your comments when the code changes. A good rule of thumb is: if you touch the code, review the comments.

• Focus on the Why, Not the What: Good comments explain why a particular decision was made rather than describing what the code is doing:
  

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

This comment explains why sorting is necessary before the search, adding valuable context.

---

---

Conclusion ✅

While comments can be helpful, the Clean Code teaches us that they should be used sparingly and purposefully.

The goal is to write code that is so clear that comments become almost unnecessary.

When comments are required, make sure they are meaningful and accurate, and provide value to anyone reading your code.

By following these guidelines, you'll not only improve the quality of your code but also make it easier for others (and your future self) to understand and maintain it.

Happy coding!

The above is the detailed content of Understanding Clean Code: Comments ⚡️. For more information, please follow other related articles on the PHP Chinese website!