注释规范

注释是代码可读性和可维护性的重要组成部分。良好的注释规范能帮助团队高效协作，减少理解成本，尤其在JavaScript这种灵活多变的语言中更为关键。

单行注释规范

单行注释以双斜杠//开头，注释内容与符号之间保留一个空格。适用于简短的代码说明或临时调试：

// 计算用户积分总和
const totalScore = user.scores.reduce((a, b) => a + b, 0);

// TODO: 需要优化性能问题
function processData() { /* ... */ }

特殊情况处理：

• 当注释在代码行末尾时，代码与注释之间至少保留两个空格：

const threshold = 0.8;  // 系统默认阈值

• 连续单行注释形成注释块时，保持对齐：

// 初始化配置参数
// 这些值会在运行时被覆盖
// 默认值仅用于开发环境
const config = loadDefaults();

多行注释规范

多行注释采用/** ... */格式，通常用于文件头部或函数说明：

/**
 * 生成指定范围的随机整数
 * @param {number} min - 最小值（包含）
 * @param {number} max - 最大值（包含）
 * @returns {number} 随机整数
 */
function getRandomInt(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

关键要素包括：

1. 首行和末行的/**与*/单独成行
2. 每行注释以*开头且对齐
3. 参数说明使用@param标签，返回值使用@returns

JSDoc注释规范

JSDoc是JavaScript的标准文档注释系统，支持类型检查和IDE智能提示：

/**
 * 用户账户类
 * @class
 * @property {string} username - 登录用户名
 * @property {Date} registerDate - 注册时间
 */
class UserAccount {
  /**
   * @constructor
   * @param {Object} options - 初始化选项
   * @param {string} options.username - 必须包含@符号
   * @param {number} [options.age=18] - 可选年龄参数
   */
  constructor(options) {
    /** @private */
    this._token = generateToken();
  }
}

常用标签示例：

• @type {string} 类型定义
• @typedef {Object} UserProfile 自定义类型
• @deprecated 标记废弃方法
• @throws {Error} 可能抛出的错误

特殊注释标记

特定场景下的标准化注释：

1. 调试标记：

// FIXME: 异步回调可能导致内存泄漏
function fetchData() {
  // DEBUG: 临时日志输出
  console.log(data);
}

2. 任务管理：

// TODO: 需要实现缓存机制
// HACK: 临时解决方案，待重构

3. 条件编译（配合构建工具）：

/* #if ENV === 'development' */
mockAPI();
/* #endif */

模块注释规范

对于ES模块或CommonJS模块，建议添加模块级注释：

/**
 * 用户认证模块
 * @module auth
 * @description 提供登录/注销/权限验证功能
 * @author team@example.com
 * @version 1.2.0
 */

/**
 * 验证JWT令牌
 * @param {string} token - 待验证的令牌
 * @returns {Promise<boolean>}
 */
export async function verifyToken(token) { /* ... */ }

注释内容准则

1. 避免冗余注释：

// 不好的示例
let count = 0; // 设置count为0

// 好的示例
// 重置投票计数器
let count = 0;

2. 解释为什么而非是什么：

// 使用位运算替代Math.floor提升性能
const index = value >> 0;

3. 复杂算法注释：

// 使用Floyd判圈算法检测链表循环
function hasCycle(head) {
  let slow = head;
  let fast = head;
  while (fast && fast.next) {
    slow = slow.next;
    fast = fast.next.next;
    if (slow === fast) return true;
  }
  return false;
}

注释与类型系统

结合TypeScript或Flow类型时：

interface Pagination {
  /** 当前页码，从1开始计数 */
  current: number;
  
  /**
   * 每页显示条数
   * @default 10
   */
  pageSize?: number;
}

/**
 * 分页查询结果
 * @template T
 */
type PageResult<T> = {
  data: T[];
  total: number;
};

注释工具链

1. 文档生成：

   • JSDoc
   • TypeDoc
   • ESDoc

2. 代码质量检查：

   // .eslintrc.json
   {
     "rules": {
       "valid-jsdoc": ["error", {
         "requireReturn": false,
         "prefer": { "returns": "return" }
       }]
     }
   }
   

3. IDE集成：

   • VS Code的Document This插件
   • WebStorm的JSDoc自动补全

注释与版本控制

在Git仓库中需要注意：

• 避免提交调试用的console.log注释
• 及时清理TODO注释中的已实现功能
• 使用@since标记版本变更：

/**
 * 新版加密算法
 * @since v2.1.0
 * @deprecated 请使用encryptV3
 */
function encryptV2() {}

注释的坏味道

需要重构的注释特征：

1. 注释掉的废弃代码块
2. 与实现逻辑不符的过期注释
3. 大段解释"这是什么"的注释（说明应该重构代码）
4. 情绪化内容（如"这个bug太愚蠢了"）

// 反模式示例
// 这个函数是John在2015年写的，不知道为什么这样实现
// 但修改它会引发生产事故，所以千万别动！
function magicCalculation() {
  /* 神秘逻辑 */
}