了解干净的代码：评论⚡️

代码注释在软件开发中被认为是必要的，但是《Clean Code》一书建议代码应该是不言自明的，不需要注释。

我们将探索何时使用注释、何时避免它们，以及如何在 JavaScript 代码中编写有价值的注释。

---

?何时避免发表评论

1. 明显的代码：

如果代码本身已经很清楚，则不应使用注释来解释代码正在做什么。

例如：

// Increment the counter by 1
counter++;

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

在这些情况下，注释是多余的，因为代码是不言自明的。不要添加不必要的注释，而是专注于使代码更具可读性。

2. 误导性评论：

与代码不匹配的注释可能会导致混乱和错误。如果你更新了代码但忘记更新注释，就会产生误导：

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

这里的注释具有误导性，可能会让稍后阅读代码的人感到困惑。最好删除注释或确保它准确反映代码。

3. 注释掉的代码：

将旧代码注释掉是一种常见的不良做法。它使代码库变得混乱并且可能会造成混乱：

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

// New code
let data = fetchDataFromDatabase();

不要将旧代码注释掉，而是使用 Git 等版本控制系统来跟踪代码更改。这可以让你的代码库保持干净和专注。

---

---

？何时使用注释

1. 明确意图：

如果一段代码具有复杂的逻辑或涉及解决方法，注释可以阐明代码存在的原因：

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

评论解释了为什么代码是必要的，为未来的开发人员提供了有价值的背景。

2. 法律信息：

有时，出于法律原因，注释是必要的，例如包含版权信息或许可详细信息：

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

这些注释至关重要，应根据项目许可的要求包含在内。

3. 决定说明：

当代码中的特定决策需要论证时，注释可能会有所帮助：

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

此评论解释了为什么选择二分搜索，提供了对实现背后的推理的深入了解。

4. 公共API：

在编写面向公众的 API 时，注释可以帮助记录如何使用它们，尤其是在您可能没有内置文档工具的 JavaScript 中：

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

在这种情况下，注释提供了有关如何使用该函数的清晰文档，这对于可能使用它的其他开发人员特别有用。

---

---

？撰写有用的评论

• 清晰简洁：评论应该直截了当、切中要点。避免编写可以从代码本身轻松理解的冗长解释。

• 避免行话：使用易于理解的语言，避免使用每个阅读代码的人可能不熟悉的技术术语。

• 更新评论：代码更改时始终更新您的评论。一个好的经验法则是：如果您触摸了代码，请查看注释。

• 关注原因，而不是内容：好的注释解释了为什么做出特定决定，而不是描述代码正在做什么：
  

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

此评论解释了为什么在搜索之前需要排序，添加了有价值的上下文。

---

---

结论✅

虽然注释可能会有所帮助，但清洁代码告诉我们应该谨慎且有目的地使用它们。

我们的目标是编写清晰的代码，几乎不需要注释。

当需要注释时，请确保它们有意义且准确，并为阅读您代码的任何人提供价值。

通过遵循这些准则，您不仅可以提高代码的质量，还可以让其他人（以及未来的您）更容易理解和维护代码。

编码愉快！

以上是了解干净的代码：评论⚡️的详细内容。更多信息请关注PHP中文网其他相关文章！