JavaScript 注释：单行注释、多行注释与使用时机

两种注释

JavaScript 有两种注释语法。单行注释以 // 开头，一直持续到行尾：

// This is a single-line comment
let price = 100; // Comments can also trail code

console.log(price);

块注释以 /* 开头，到下一个 */ 结束。它可以跨越任意多行：

/*
  This is a block comment.
  It spans multiple lines.
  The interpreter ignores all of it.
*/

let total = 42;
console.log(total);

这两种形式都会被 JavaScript 引擎完全忽略。它们是写给人看的：给你自己，给你的队友，也给六个月后读这段代码的你。

单行注释

// 是你最常用的一种。同一行中 // 之后的所有内容都是注释，下一行又回到代码：

// Calculate the tax-inclusive price
const price = 100;
const taxRate = 0.08;
const total = price * (1 + taxRate); // final amount the customer pays

console.log(total);

尾随注释（写在语句之后）适合简短的说明。如果说明长到需要换行，就把它挪到代码上方单独一行：过长的尾随注释会被编辑器截断，也会被读者忽略。

块注释

在两种情况下值得使用 /* */：注释需要不止一行，或者注释要放在表达式中间。

/*
 * Applies a bulk discount when the order qualifies.
 * Rules change per quarter - see pricing spec #214.
 */
function bulkDiscount(quantity, unitPrice) {
    return quantity >= 10 ? unitPrice * 0.9 : unitPrice;
}

// Inline in the middle of an expression:
const area = /* width */ 10 * /* height */ 5;

console.log(bulkDiscount(12, 50));
console.log(area);

有一个陷阱：块注释不能嵌套。第一个 */ 就会结束注释，哪怕你以为自己还在外层注释里面：

/* outer /* inner */ still outer */
// SyntaxError - the first */ closed the block,
// and "still outer */" is now invalid code.

如果要注释掉的代码里本身已经包含 /* */，就改为在每一行前加 //。

注释掉代码

调试时，你经常需要暂时禁用几行代码。两种注释形式都可以：

function checkout(cart) {
    const subtotal = cart.reduce((sum, item) => sum + item.price, 0);

    // const shipping = calculateShipping(cart);
    // const total = subtotal + shipping;

    /*
    if (cart.length === 0) {
        throw new Error("Cart is empty");
    }
    */

    return subtotal;
}

console.log(checkout([{ price: 10 }, { price: 20 }]));

每个编辑器都有对应的快捷键：Windows 和 Linux 上是 Ctrl+/，Mac 上是 Cmd+/，它会为选中的行切换 // 注释。学会一次，你每天都会用到。

被注释掉的代码只应该是临时的。不要把一堆写着 // old version, keep just in case 的废弃代码提交上去。版本控制会替你记住旧代码，直接删掉就好。

注释写“为什么”，而不是“做了什么”

区分有用注释和噪音，就靠这一条规则。代码已经展示了它做了什么，好的注释要解释为什么。

噪音：

// Set x to 10
let x = 10;

// Loop through the array
for (let i = 0; i < x; i++) {
    // Add i to the total
    console.log(i);
}

这些注释没有告诉读者任何代码本身没说的东西。对比一下：

// Stripe caps description at 500 chars - truncate before sending
function prepareDescription(text) {
    return text.slice(0, 500);
}

// Retry once: the auth service has a known cold-start timeout on first request
async function fetchUser(id) {
    try {
        return await api.get(`/users/${id}`);
    } catch {
        return await api.get(`/users/${id}`);
    }
}

这两条注释都提到了读者单看代码无法得知的信息：一个外部限制，一个有据可查的怪异行为。这就是标准。如果删掉某条注释不会让任何人困惑，那它就没有发挥作用。

JSDoc：给工具读的注释

JSDoc 是一种约定，用结构化的块注释来描述函数。编辑器和类型检查器会读取它们，为你提供更好的自动补全和悬停提示文档：

/**
 * Returns the final price after applying a percentage discount.
 *
 * @param {number} price - The original price in cents.
 * @param {number} percent - Discount percentage, 0 to 100.
 * @returns {number} The discounted price in cents.
 */
function discount(price, percent) {
    return price * (1 - percent / 100);
}

console.log(discount(10000, 20));

开头的 /**（两个星号）就是它被识别为 JSDoc 而不是普通块注释的标志。你不需要给每个函数都写 JSDoc，它最适合用在公开 API、共享的工具函数，以及代码本身看不出类型的地方。

几个值得保持的习惯

• 让注释紧挨着它所描述的代码。 写在相关代码上方十行处的注释，随着代码变化很容易与代码脱节。
• 修改代码时同步更新注释。 过时的注释比没有注释更糟，它会误导下一个读者。
• 起更好的名字，而不是写更多的注释。 const d = 86400000; 需要注释，const MILLISECONDS_PER_DAY = 86_400_000; 就不需要。
• 用 TODO: 或 FIXME: 标记临时问题。 大多数编辑器会高亮它们，以后用 grep 搜索也很方便。

// TODO: handle timezone offsets properly once the date library is upgraded
function daysBetween(a, b) {
    const MS_PER_DAY = 86_400_000;
    return Math.round((b - a) / MS_PER_DAY);
}

const start = new Date("2024-01-01");
const end = new Date("2024-01-15");
console.log(daysBetween(start, end));

HTML 注释与 JavaScript 注释

如果你在 HTML 文件里写 JavaScript，不要把两种注释风格弄混。HTML 使用 <!-- -->，JavaScript 使用 // 和 /* */。在 <script> 标签内部，只有 JavaScript 的写法有效：

<script>
    // Correct - JS comment inside <script>
    /* Also correct */
    <!-- Wrong - this is an HTML comment and will break your JS -->
    console.log("hi");
</script>

出于兼容古老浏览器的历史原因，浏览器曾经容忍脚本中出现 <!-- -->，但你应该把它当作错误写法，不要再用。

下一步：声明变量

现在你已经会给代码加注释了，是时候写点代码了。JavaScript 有三种声明变量的方式：let、const 和 var。选对其中一种，是你在每一行代码上要做的第一个真正的决定。下一篇就讲这个。