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

= JavaScript注释规范 =

良好的注释规范是编写可维护、易读JavaScript代码的关键部分。注释不仅能帮助他人理解代码逻辑，也能帮助开发者自己在未来回顾代码时快速理解。

== 注释的作用 ==
JavaScript注释主要有以下用途：
* '''解释代码意图'''：说明代码的目的和设计思路
* '''标记待办事项'''：使用TODO、FIXME等标记
* '''生成文档'''：通过JSDoc生成API文档
* '''临时禁用代码'''：调试时暂时注释掉部分代码

== 注释类型 ==
JavaScript支持两种注释语法：

=== 单行注释 ===
使用双斜杠<code>//</code>，适用于简短说明：

<syntaxhighlight lang="javascript">
// 计算商品总价
const total = price * quantity;
</syntaxhighlight>

=== 多行注释 ===
使用<code>/* */</code>，适合较长的说明：

<syntaxhighlight lang="javascript">
/*
 * 这个函数计算订单折扣
 * 参数：
 *   - amount: 订单金额
 *   - isMember: 是否是会员
 * 返回折扣率(0-1)
 */
function getDiscount(amount, isMember) {
  // 函数实现...
}
</syntaxhighlight>

== 最佳实践 ==

=== 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>

== 注释风格指南 ==

=== 1. 文件头注释 ===
每个文件顶部建议包含：

<syntaxhighlight lang="javascript">
/**
 * @file 用户认证模块
 * @author 张三
 * @version 1.0.0
 * @license MIT
 * @description 处理用户注册、登录和权限验证
 */
</syntaxhighlight>

=== 2. 函数注释 ===
使用JSDoc规范：

<mermaid>
classDiagram
    class FunctionComment {
        +description: string
        +@param: Param[]
        +@returns: string
        +@throws: string[]
        +@example: string
    }
    class Param {
        +name: string
        +type: string
        +description: string
    }
</mermaid>

=== 3. 复杂逻辑注释 ===
对复杂算法添加说明：

<syntaxhighlight lang="javascript">
// 使用Dijkstra算法计算最短路径
// 1. 初始化距离数组，设置起点距离为0
// 2. 创建未访问节点集合
// 3. 当未访问集合不为空时：
//    a. 选择当前距离最小的节点
//    b. 更新邻居节点的距离
//    c. 标记当前节点为已访问
function dijkstra(graph, start) {...}
</syntaxhighlight>

== 注释工具 ==

=== 1. 文档生成 ===
* JSDoc
* TypeDoc
* ESDoc

=== 2. 代码检查 ===
ESLint规则：
* <code>valid-jsdoc</code>
* <code>require-jsdoc</code>
* <code>no-warning-comments</code> (限制TODO/FIXME)

== 数学公式示例 ==
当注释涉及数学公式时：

<math>
E = mc^2
</math>

或更复杂的公式：

<math>
\sum_{i=1}^n i^2 = \frac{n(n+1)(2n+1)}{6}
</math>

== 总结 ==
良好的注释规范应该：
* 遵循项目或团队的统一风格
* 保持简洁但信息丰富
* 随代码更新而同步更新
* 使用工具自动检查
* 平衡注释量与代码自解释性

记住：'''最好的注释是那些不需要的注释'''——通过清晰的代码结构和有意义的命名来减少对注释的依赖。

[[Category:编程语言]]
[[Category:JavaScript]]
[[Category:Javascript最佳实践]]