React+TypeScript代码注释规范指南

一、注释的意义

为什么要写注释？

增强可读性

注释可以帮助他人（甚至未来的自己）更快理解代码意图和业务逻辑，避免重新摸索思路。
提高可维护性

随着项目变大，注释可以帮助开发者快速定位功能和模块职责，降低后期维护成本。
便于协作开发

在多人协作的项目中，注释能统一理解、减少沟通成本，尤其是在代码评审或交接时尤为重要。
便于文档生成

使用标准化注释（如 JSDoc / TSDoc）可以自动生成 API 文档，提高效率。

不写注释的危害

代码难以理解，增加沟通和学习成本
降低团队整体开发效率，阻碍新成员上手
难以排查 Bug，增加维护代价
引发误解和误用，造成错误业务实现

二、需要注释的内容与注释方式

推荐使用风格：JSDoc / TSDoc

适用于函数、变量、组件、类型定义等，方便 IDE 智能提示和文档生成。

1. 组件注释（React 函数组件）

TypeScript 复制代码

/**
 * 用户登录组件
 * @description 允许用户输入账号和密码进行登录操作。
 * @returns 登录表单视图
 */
const LoginForm: React.FC = () => {
  // ...
}

2. 函数或方法注释

TypeScript 复制代码

/**
 * 根据用户 ID 获取用户信息
 * @param userId 用户唯一标识
 * @returns 用户信息 Promise
 */
async function fetchUserInfo(userId: string): Promise<User> {
  // ...
}

3. 复杂逻辑或业务处理（在函数内部的复杂逻辑）

TypeScript 复制代码

const transformFormData = (data: FormValues): RequestPayload => {
  const payload: RequestPayload = {
    username: data.name.trim(),
    age: Number(data.age),
    // 地址字段永远不变
    address: data.address,
  };

  // 以下是复杂处理逻辑：
  // 1. 日期字段需要从用户选择的本地格式（YYYY/MM/DD）转换为 ISO 字符串
  // 2. 若未选择日期，则使用当前时间
  if (data.date) {
    const localDate = new Date(data.date); // 假设 data.date 是字符串类型
    payload.date = localDate.toISOString();
  } else {
    payload.date = new Date().toISOString();
  }

  // 3. 标签数组需要过滤掉空值，并拼接成逗号分隔字符串
  if (Array.isArray(data.tags)) {
    const validTags = data.tags.filter(Boolean); // 过滤 null/undefined/空字符串
    payload.tags = validTags.join(',');
  }

  return payload;
};

4. 类型定义注释

TypeScript 复制代码

/**
 * 表单字段类型定义
 */
type LoginFormValues = {
  /** 用户名 */
  username: string;

  /** 密码，至少6位 */
  password: string;
};

5. TODO / FIXME 说明

TypeScript 复制代码

// TODO: 后续支持手机号登录
// FIXME: 临时处理，后续优化接口请求防抖逻辑

Tips：VSCode可配合文章中的Todo tree插件使用，Webstorm本身支持。

WebStorm转VSCode：高效迁移指南-CSDN博客

三、好的注释 VS 坏的注释（对比示例）

✅ 好的注释示例

TypeScript 复制代码

/**
 * @param delay 延迟时间（单位：毫秒）
 * @description 触发后等待指定时间再执行回调
 */
function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): T {
  // ...
}

优点

描述了每个参数的用途
指明了行为和执行时机
遵循 TSDoc 格式，便于自动生成文档

❌ 坏的注释示例

TypeScript 复制代码

// 防抖函数
function debounce(fn, delay) {
  // 等一下再执行
}

缺点

不明确参数类型和单位
缺少函数行为说明
不符合规范，无法被识别生成文档

❌ 多余或错误注释

TypeScript 复制代码

let count = 0; // 声明变量 count

问题

注释内容无意义，重复表达代码本身意图
容易造成维护负担（代码变更但注释未变）

四、总结：如何写出"高质量注释"？

原则	说明
准确	注释要真实反映代码行为
简洁	使用简洁明了的语言，不堆砌
及时	与代码同步更新，避免失效注释
聚焦	注释描述"为什么"和"做什么"，避免翻译代码
标准	使用统一的格式（如 TSDoc）

五、可选补充：团队规范建议

组件顶部必须有 TSDoc 注释
所有公共函数都需说明参数和返回值
复杂业务逻辑块前必须注释意图与处理思路
使用 TODO 和 FIXME 标签追踪临时逻辑
使用eslint-plugin-tsdoc规范项目注释。