comment

Code Commenting Guidelines

基本原则 Basic Principles

• 注释应该解释为什么这样做，而不是做了什么
• 代码即文档，仅在必要时添加注释
• 使用清晰简洁的语言，避免冗余, English
• 及时更新注释，确保与代码同步

文件头注释 File Header Comments

/**
 * @file 文件的简要描述
 * @description 详细描述文件的功能和用途
 * @author [作者名称]
 * @date YYYY-MM-DD
 */

函数注释 Function Comments

/**
 * 函数的简要描述
 * @description 详细描述函数的功能
 * @param {string} param1 - 参数1的描述
 * @param {number} param2 - 参数2的描述
 * @returns {Promise<boolean>} 返回值的描述
 * @throws {Error} 可能抛出的错误
 * @example
 * const result = await someFunction('test', 123);
 */
function someFunction(param1: string, param2: number): Promise<boolean> {
  // ...
}

行内注释 Inline Comments

// ✅ 好的注释：解释复杂的业务逻辑
if (user.role === 'admin' && !isHoliday) {
  // 管理员在非假日期间具有特殊权限
  grantSpecialAccess();
}

// ❌ 不好的注释：陈述显而易见的事实
// 检查用户是否为管理员
if (user.role === 'admin') {
  // ...
}

待办注释 TODO Comments

// TODO(github-username): 实现用户认证功能 (#123)
// FIXME(github-username): 修复内存泄漏问题 (#456)
// NOTE: 这里使用递归可能会导致性能问题

类型定义注释 Type Definition Comments

/**
 * 用户配置接口
 * @interface UserConfig
 * @property {string} name - 用户名
 * @property {number} age - 年龄
 * @property {string[]} permissions - 权限列表
 */
interface UserConfig {
  name: string;
  age: number;
  permissions: string[];
}

常量和枚举注释 Constants and Enum Comments

/**
 * 用户角色枚举
 * @enum {string}
 */
enum UserRole {
  /** 管理员用户 */
  ADMIN = 'admin',
  /** 普通用户 */
  USER = 'user',
  /** 访客用户 */
  GUEST = 'guest',
}

/** 最大重试次数 */
const MAX_RETRY_COUNT = 3;

弃用注释 Deprecation Comments

/**
 * @deprecated 从 v2.0.0 开始弃用，请使用 `newFunction()` 替代
 * @see {@link newFunction}
 */
function oldFunction() {
  // ...
}

区块注释 Section Comments

//===================================
// 初始化配置
//===================================

//===================================
// 工具函数
//===================================

//===================================
// 事件处理
//===================================