Vue 项目注释与命名规范

本 Skill 旨在统一 Vue 项目中的代码注释格式与命名约定，建立标准化的开发规范。不仅涵盖组件 Props，还包括函数、变量、类型定义以及文件目录的命名规则。

默认遵循 wot-ui-component-baseline 中的共享约束。

职责边界

• 本 Skill 只负责源码层面的命名与注释规范。
• 不负责创建组件骨架，相关工作交给 create-component。
• 不负责 Demo 页编排，相关工作交给 create-demo-page。
• 不负责 Markdown 文档迁移与 API 表维护，相关工作交给 migrate-component-doc。

使用场景

1. 代码维护: 统一现有代码库的风格，提高可读性。
2. 新功能开发: 确保新增组件和逻辑符合团队规范。
3. Code Review: 作为代码审查的标准依据。
4. 组件补注释: 在新建组件后补齐 types.ts、公共函数和类型定义注释。

1. 命名规范

遵循 "约定优于配置" 原则，保持命名的一致性与语义化。

1.1 文件与目录

• 组件文件: 使用 kebab-case (短横线连接)，如 my-component.vue, user-profile.vue。
• 普通 TS/JS 文件: 使用 kebab-case，如 date-utils.ts, api-client.ts。
• 目录: 使用 kebab-case，如 components/, utils/, user-center/。

1.2 变量与常量

• 普通变量: 使用 camelCase (小驼峰)，如 userInfo, isLoading。
  • 布尔类型建议以 is, has, should 开头，如 isVisible。
• 常量: 使用 UPPER_SNAKE_CASE (大写下划线)，通常用于全局配置或某些固定值，如 MAX_RETRY_COUNT, DEFAULT_THEME。
• 私有变量: 即使在 TS 中有 private 关键字，Vue 3 组合式 API 中内部变量仍建议保持 camelCase，不强制加下划线前缀，除非团队有特殊约定。

1.3 函数

• 函数名: 使用 camelCase (小驼峰)。
• 命名动词: 建议使用动词开头，如 get, set, fetch, handle, on, render 等。
  • handle: 用于事件处理，如 handleClick。
  • fetch/request: 用于异步请求，如 fetchUserData。
  • get: 用于获取数据或计算结果，如 getFormattedDate。

1.4 类与类型

• 类 (Class): 使用 PascalCase (大驼峰)，如 User, HttpClient。
• 接口 (Interface) / 类型别名 (Type): 使用 PascalCase (大驼峰)，如 UserProps, TableColumn。
• 枚举 (Enum): 使用 PascalCase，成员使用 UPPER_SNAKE_CASE (视团队习惯，也可 PascalCase)。

---

2. 注释规范

所有注释应简洁明了，使用中文（除非项目强制全英文），并保持语意通顺。

2.1 组件 Props 注释

组件 Props 注释是源码可读性与 API 提示的重要来源。

基本格式:

/**
 * 属性简短描述
 * 类型: xxx
 * 可选值: A | B | C
 * 默认值: xxx
 */

规则:

1. 使用多行 JSDoc (/** ... */)。
2. 描述: 第一行简述作用。
3. 类型: 如果使用了复杂类型或需要明确说明，使用 类型: TypeName。
4. 可选值: 枚举类型必填，格式 可选值: 'a' | 'b'。
5. 默认值: 必填，格式 默认值: value。若是继承属性，写 默认值: 继承自 xxx。

2.2 函数/方法注释

关键业务逻辑函数、公共工具函数必须添加 JSDoc 注释。

基本格式:

/**
 * 函数功能简述
 * @param {Type} paramName 参数说明
 * @returns {Type} 返回值说明
 */

规则:

1. 简单的一行函数可省略注释或用单行注释。
2. 复杂逻辑或公共接口使用 JSDoc。
3. @param: 描述参数名、类型及含义。
4. @returns: 描述返回值类型及含义 (如果是 void 可省略)。

2.3 变量注释

规则:

1. 普通变量: 简单变量可不注，或使用单行注释 // ... 放在变量声明行上方或右侧。
2. 关键状态: 涉及复杂业务状态的变量，建议使用 JSDoc 或详细的单行注释。

2.4 类型定义 (Types/Interfaces) 注释

规则:

1. 接口/类型说明: 使用 JSDoc 说明该 Type/Interface 的用途。
2. 属性说明: 建议使用 JSDoc (/** ... */) 以便编辑器提示，或使用单行注释。

---

3. 示例集合

3.1 综合示例 (组件内部)

// types.ts
/**
 * 用户信息接口
 */
export interface UserInfo {
  /** 用户 ID */
  id: number
  /** 用户名 */
  name: string
  /**
   * 用户角色
   * 可选值: 'admin' | 'editor' | 'guest'
   */
  role: 'admin' | 'editor' | 'guest'
}

// my-component.vue (Script Setup)
import { defineProps } from 'vue'
import type { UserInfo } from './types'

// 常量定义
const MAX_ITEM_COUNT = 10

export const myComponentProps = {
  /**
   * 绑定的值
   * 类型: string | number
   * 默认值: ''
   */
  modelValue: {
    type: [String, Number],
    default: ''
  },
  /**
   * 按钮类型
   * 可选值: 'primary' | 'success' | 'warning'
   * 默认值: 'primary'
   */
  type: {
    type: String,
    default: 'primary'
  },
  /**
   * 是否禁用
   * 默认值: false
   */
  disabled: Boolean
}

// 变量定义
const isVisible = ref(false)

/**
 * 处理点击事件，提交用户信息
 * @param {UserInfo} user 当前操作的用户
 * @returns {Promise<void>}
 */
const handleSubmit = async (user: UserInfo) => {
  if (user.role === 'guest') {
    return
  }
  // ... logic
}

输出解释

执行此技能后，代码将符合上述规范：

• 命名: 文件、变量、函数严格遵守大小写约定。
• 注释: Props、函数、类型定义拥有清晰、标准化的 JSDoc 注释。
• 一致性: 整个项目源码风格统一，便于维护与审查。