yy-comment

When to use

• 用户要求为代码文件添加注释时
• 用户要求为特定函数添加注释时
• 用户说"给这个文件加注释"、"添加 JSDoc"、"补充函数注释"时
• 用户说"给 xxx 函数加注释"、"为 xxx 函数添加文档"时
• 需要为 TypeScript/JavaScript 文件中的函数添加文档注释时

Don't use when

• 用户要求直接实现新功能时
• 用户要求修改代码逻辑时
• 用户要求删除代码时
• 文件或函数已有完整注释，用户未明确要求补充时

Steps

1. 确定注释范围

   • 若用户指定文件：读取目标文件内容，识别所有函数定义
   • 若用户指定特定函数：定位目标函数，分析其功能和参数
   • 若用户未指定：询问用户需要为整个文件还是特定函数添加注释

2. 添加 JSDoc 注释

   • 在每个函数定义上方添加 JSDoc 注释
   • 包含函数功能描述
   • 使用 @param 标签描述参数
   • 使用 @returns 标签描述返回值
   • 使用 @throws 标签描述可能抛出的异常（如有）

3. 添加内部注释

   • 识别函数体内部的重要逻辑
   • 在关键步骤前添加单行注释
   • 注释应解释"为什么"而非"是什么"
   • 避免对显而易见的代码添加注释

4. 输出结果

   • 列出添加注释的函数列表
   • 说明每个函数添加的注释内容

JSDoc 规范

基本格式

/**
 * 函数功能描述
 * @param paramName - 参数说明
 * @returns 返回值说明
 */

包含异常说明

/**
 * 函数功能描述
 * @param filePath - 文件绝对路径
 * @returns 解析后的对象
 * @throws 若文件不存在或格式错误则抛出错误
 */

包含多行说明

/**
 * 函数功能描述
 *
 * 处理逻辑：
 * 1. 第一步说明
 * 2. 第二步说明
 * 3. 第三步说明
 *
 * @param dirPath - 目录绝对路径
 * @returns 处理结果
 */

内部注释规范

添加注释的场景

• 复杂的算法逻辑
• 非直观的业务规则
• 重要的分支判断
• 递归调用
• 特殊处理的边界情况

注释格式

function processData(data: Data[]): Result {
  // 单独处理首条记录，作为基准值
  const baseline = data[0];

  // 递归处理嵌套结构
  for (const item of data) {
    processItem(item);
  }

  // 合并并排序结果
  return sortResults(results);
}

避免的注释

// ❌ 显而易见的注释
i = i + 1; // i 加 1

// ❌ 重复代码的注释
// 遍历数组
for (const item of items) {
  // ...
}

Output contract

• 修改文件列表：列出所有添加注释的文件路径
• 函数注释统计：每个文件添加 JSDoc 的函数数量
• 内部注释统计：每个文件添加内部注释的数量

注意事项

• 注释使用中文编写
• JSDoc 注释需包含 @param 和 @returns 标签
• 仅对重要逻辑添加内部注释，避免过度注释
• 保持注释简洁，一行即可说明清楚