编辑“︁JavaScript注释规范”︁（章节）

== 最佳实践 ==

=== 1. 解释"为什么"而非"是什么" ===
避免描述代码本身做什么，而是解释为什么这样写：

<syntaxhighlight lang="javascript">
// 不好：描述代码做什么
// 循环数组元素
for (let i = 0; i < arr.length; i++) {...}

// 好：解释为什么
// 使用传统for循环而非forEach，因为需要提前退出
for (let i = 0; i < arr.length; i++) {...}
</syntaxhighlight>

=== 2. 使用JSDoc规范 ===
JSDoc是广泛使用的文档注释标准：

<syntaxhighlight lang="javascript">
/**
 * 计算两个数的和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两个参数的和
 * @throws {TypeError} 当参数不是数字时
 */
function sum(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new TypeError('参数必须是数字');
  }
  return a + b;
}
</syntaxhighlight>

=== 3. 避免过度注释 ===
好的代码应该自解释，只在必要时添加注释：

<syntaxhighlight lang="javascript">
// 不好：不必要的注释
const age = 25; // 设置age为25

// 好：有意义的变量名使注释多余
const minimumVotingAge = 18;
</syntaxhighlight>

=== 4. 标记待办事项 ===
使用统一前缀标记需要后续处理的代码：

<syntaxhighlight lang="javascript">
// TODO: 添加错误处理
// FIXME: 临时解决方案，需要重构
// OPTIMIZE: 这里可能有性能问题
</syntaxhighlight>