文档基础 documentation-fundamentals

---

name: documentation-fundamentals description: 指导文档标准，包括READMEs、JSDoc和代码注释。在编写文档、添加注释或解释代码时使用。强制执行“为什么而非什么”原则。

文档基础回顾

“代码告诉你如何，注释告诉你为什么。如果你只解释代码做什么，你是在浪费每个人的时间。”

何时应用

激活此技能时：

• 审查或创建README文件
• 编写JSDoc/docstring注释
• 行内代码注释
• API文档
• 架构决策记录

---

黄金法则：为什么，而非什么

// ❌ 差：解释什么（代码已经说明了这个）
// 计数器加1
counter++;

// ✅ 好：解释为什么（代码无法提供的上下文）
// 计数器必须在验证运行前递增，
// 以处理初始值为0的边缘情况
counter++;

---

README结构（五个要点）

每个README必须回答这些问题：

1. 这是什么？（一句话）

“用一句话描述它解决了什么问题？”

## 什么

一个将Figma设计转换为React组件的CLI工具。

2. 为什么存在？

“什么痛点促使了这个项目？”

## 为什么

手动将设计转换为代码需要数小时并引入不一致性。
这个工具自动化了过程，确保像素级完美的组件。

3. 如何安装

“可复制的、能工作的指令。”

## 安装

npm install your-package

4. 如何使用

“最简单有效的示例。”

## 快速开始

npx your-tool --input design.fig --output ./components

5. 如何贡献（可选）

“对于开源项目。”

## 贡献

1. Fork仓库
2. 创建功能分支
3. 提交拉取请求

---

注释类型及何时使用

函数/方法文档（JSDoc）

/**
 * 验证电子邮件格式并检查域名是否在黑名单中。
 *
 * @param email - 要验证的电子邮件地址
 * @returns ValidationResult，包含成功状态和错误消息
 *
 * @example
 * const result = validateEmail('user@example.com');
 * if (!result.success) {
 *   showError(result.error);
 * }
 *
 * 注意：这使用RFC 5322正则表达式模式，故意严格以防止一次性电子邮件地址。
 */
function validateEmail(email: string): ValidationResult {
  // 实现
}

行内注释（仅用于为什么）

// 速率限制为100/分钟，但我们使用80以留出重试空间
const RATE_LIMIT = 80;

// 降序排序，因为新项目应首先显示
//（产品经理的业务要求 - 见工单#1234）
items.sort((a, b) => b.date - a.date);

// 黑客：API以字符串返回日期，需要手动解析
// 待办：后端迁移后删除（2026年第二季度）
const date = new Date(response.dateString);

块注释（复杂逻辑）

/*
 * 认证流程：
 * 1. 检查本地令牌缓存
 * 2. 如果过期，尝试静默刷新
 * 3. 如果刷新失败，重定向到登录
 *
 * 我们使用刷新令牌而非重新认证，以避免长时间会话中打扰用户体验。
 */

---

常见错误（反模式）

1. 注释显而易见的内容

// ❌ 差：无用的注释
// 将名字设置为“John”
const name = "John";

// 获取用户年龄
const age = user.age;

// 遍历项目
for (const item of items) { ... }

// ✅ 好：无需注释（代码自解释）
const name = "John";

2. 过时的注释

// ❌ 差：注释与代码不匹配（危险！）
// 过滤非活跃用户
const users = data.filter(u => u.role === 'admin');

// ✅ 好：注释反映现实
// 管理视图中仅显示管理员用户
const users = data.filter(u => u.role === 'admin');

3. 无上下文的魔法数字

// ❌ 差：86400是什么？
const expiresIn = 86400;

// ✅ 好：解释魔法数字
const SECONDS_PER_DAY = 86400;
const expiresIn = SECONDS_PER_DAY; // 令牌在24小时后过期

4. 注释掉的代码

// ❌ 差：死代码污染文件
// const oldImplementation = () => { ... };
// function deprecatedHelper() { ... }

// ✅ 好：删除它！Git记录一切

5. 空README

<!-- ❌ 差：自动生成，从未更新 -->
# my-project

此项目使用Create React App引导。

---

苏格拉底式问题

问这些问题而非给出答案：

1. 为什么而非什么：“这个注释是否告诉了我代码没有的东西？”
2. 受众：“明天加入的开发者能理解这个吗？”
3. 维护：“如果你更改代码，你会记得更新这个注释吗？”
4. README：“有人能仅凭README指令运行这个项目吗？”
5. JSDoc：“开发者需要知道什么来正确使用这个函数？”
6. 必要性：“如果你删除这个注释，会丢失什么吗？”

---

README模板

# 项目名称

一句话描述此项目功能。

## 为什么

解决的问题及其重要性。

## 安装

npm install project-name

## 快速开始

最小可工作代码示例。

## API

### 函数名(参数)

描述其功能。

**参数：**
- `param` (string)：此参数的用途

**返回：** 返回的内容

**示例：**
```js
// 使用示例

配置

可用选项及其默认值。

贡献

如何贡献（如果适用）。

许可证

MIT（或您的许可证）

---

## JSDoc要点

```typescript
/**
 * 此函数功能的简要描述。
 *
 * @param paramName - 参数描述
 * @returns 返回值描述
 * @throws {ErrorType} 当发生此错误时
 * @example
 * // 展示如何使用
 * const result = myFunction('input');
 *
 * @see RelatedFunction 类似功能
 * @deprecated 使用newFunction替代（v2.0+）
 */

---

需指出的红旗

红旗	问题
空README	“新开发者能立即运行这个项目吗？”
// 将x设为5	“这个注释增加价值了吗？代码已经说了这个。”
过时注释	“这个注释是否仍然匹配代码功能？”
导出无JSDoc	“别人如何知道如何使用这个函数？”
注释掉的代码	“为什么在这里？Git有历史记录，如果需要可以恢复。”
魔法数字	“3600是什么意思？为什么是这个数字？”

---

面试关联

“我维护全面的文档，包括README、JSDoc注释和架构决策记录，确保代码对整个团队可维护。”

文档习惯展示：

• 沟通技巧
• 长远思维
• 团队合作精神
• 高级成熟度

---

MCP使用

Context7 - 框架文档

获取：JSDoc文档
获取：Markdown最佳实践

Octocode - 实际示例

搜索：流行仓库中的README.md模式
搜索：TypeScript项目中的JSDoc示例