写给后人看的代码：组件注释、规范、开发文档一体化方案_公共组件库如何写注释内容-优快云博客

有句前端老话说得好：

“写给自己看的叫草稿，写给别人看的才叫代码。”

但真正落到日常开发，很多组件库看起来像谜语人写的——参数含义靠猜，事件行为靠踩，文档只写“参考例子”，注释等于“// 点击按钮”。

组件是复用的单元，注释和文档是它们的说明书。 本文将带你系统梳理如何打造一套组件级别的注释 + 规范 + 文档一体化方案，让团队能用、爱用、敢用你的代码。

一、从“写注释”开始：写得明白，胜过写得完美

1. 用意图写注释，不是写翻译

// 不推荐
// 设置按钮是否禁用
disabled: boolean;

// 更好的方式
/** 
 * 是否禁用按钮交互行为。设为 true 时，按钮不会响应点击事件。
 */
disabled: boolean;

2. 注释优先写在“对组件使用者有意义”的地方

• Props 接口注释清晰（支持哪几种类型、默认值）

• Slot 插槽行为清晰说明（是否具名 / 支持哪些变量）

• 自定义事件说明清晰（事件名、触发时机、携带数据）

二、组件代码中的规范与结构建议

让代码“结构化”，后人才读得顺：

// 推荐结构顺序
<template>...</template>

<script setup lang="ts">
// 1. Props 定义
// 2. Emits 定义
// 3. 状态与计算属性
// 4. 生命周期
// 5. 逻辑函数
</script>

<style scoped>...</style>

• 每个方法上方写一句话注释说明作用

• 抽象逻辑尽量封装为 composable（如 useTooltip、useDraggable）

• 提倡“命名即注释”：不要叫 handleClick，叫 handleConfirmClick()

三、组件文档一体化生成方案

工具选型推荐：

工具	特点	适合
Storybook	组件预览 + 交互演示 + 自动生成文档	多组件库开发场景
VitePress / Docusaurus	写文档站 + 接入组件演示	官网 / 内部手册建设
vue-docgen / react-docgen	从代码中提取 props、events、slots	文档生成自动化
Typedoc	专门提取 TypeScript 类型说明	TS-heavy 项目

示例：使用 Storybook 生成组件文档

// Button.stories.ts
export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    type: {
      options: ['primary', 'secondary'],
      control: { type: 'select' },
      description: '按钮的类型（样式风格）'
    }
  }
}

效果：

• 可以在线切换 props 预览样式

• 自动导出 markdown 格式的 props 表格

• 集成单测、快照测试（视觉回归）更方便

四、文档 + 注释 + 示例一体化的推荐结构

建议为每个组件建立以下结构：

/components/Button/
├── index.vue
├── Button.stories.ts       # Storybook 示例
├── Button.test.ts          # 单测
├── README.md               # 组件说明文档
├── types.ts                # Props / Emits 类型定义
└── style/                  # 样式模块

README.md 示例内容：

# Button 按钮组件

## Props
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| type | string | primary | 按钮类型 |
| disabled | boolean | false | 是否禁用 |

## Events
- `click`: 点击按钮时触发