代码文档编写 code-documentation

---

名称: 代码文档化 描述: 编写有效的代码文档 - API文档、README文件、内联注释和技术指南。用于记录代码库、API或编写开发者指南。 来源: wshobson/agents 许可证: MIT

代码文档化

README 结构

标准 README 模板

# 项目名称

简要描述该项目的作用。

## 快速开始

```bash
npm install
npm run dev

安装

详细的安装说明…

使用

import { something } from 'project';

// 示例用法
const result = something.doThing();

API 参考

functionName(param: Type): ReturnType

描述该函数的作用。

参数:

• param - 参数描述

返回: 返回值描述

示例:

const result = functionName('value');

配置

选项	类型	默认值	描述
option1	string	'default'	它的作用

贡献

如何贡献…

许可证

MIT

## API 文档

### JSDoc/TSDoc 风格
```typescript
/**
 * 创建一个新的用户账户。
 *
 * @param userData - 用于账户创建的用户数据
 * @param options - 可选配置
 * @returns 创建的用户对象
 * @throws {ValidationError} 如果电子邮件无效
 * @example
 * ```ts
 * const user = await createUser({
 *   email: 'user@example.com',
 *   name: 'John'
 * });
 * ```
 */
async function createUser(
  userData: UserInput,
  options?: CreateOptions
): Promise<User> {
  // 实现
}

/**
 * API 客户端的配置选项。
 */
interface ClientConfig {
  /** API 基础 URL */
  baseUrl: string;
  /** 请求超时时间（毫秒） @default 5000 */
  timeout?: number;
  /** 包含在请求中的自定义头部 */
  headers?: Record<string, string>;
}

OpenAPI/Swagger

openapi: 3.0.0
info:
  title: 我的 API
  version: 1.0.0

paths:
  /users:
    post:
      summary: 创建用户
      description: 创建一个新的用户账户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 无效输入

components:
  schemas:
    UserInput:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time

内联注释

何时注释

// 好：解释为什么，而不是什么

// 使用二分搜索，因为列表总是排序的，并且可能包含数百万项 - O(log n) vs O(n)
const index = binarySearch(items, target);

// 好：解释复杂的业务逻辑
// 如果用户成为会员超过2年并且有10次以上购买，享受20%折扣（根据市场团队2024年第四季度决策）
if (user.memberYears >= 2 && user.purchaseCount >= 10) {
  applyDiscount(0.2);
}

// 好：记录变通方案
// 黑客：Safari不支持此API，回退到轮询
// 待办：当Safari添加支持时移除（跟踪：webkit.org/b/12345）
if (!window.IntersectionObserver) {
  startPolling();
}

何时不注释

// 坏：陈述显而易见的事实
// 计数器加1
counter++;

// 坏：解释清晰的代码
// 检查用户是否是管理员
if (user.role === 'admin') { ... }

// 坏：过时的注释（比没有注释更糟）
// 返回用户的全名  <-- 现在实际上返回电子邮件！
function getUserIdentifier(user) {
  return user.email;
}

架构文档

ADR（架构决策记录）

# ADR-001：使用 PostgreSQL 作为主要数据库

## 状态
已接受

## 上下文
我们需要一个数据库来存储用户数据和交易。
考虑选项：PostgreSQL、MySQL、MongoDB、DynamoDB。

## 决策
使用 PostgreSQL 并托管在 Supabase 上。

## 理由
- 财务数据需要强 ACID 合规性
- 团队有 PostgreSQL 经验
- Supabase 提供身份验证和实时功能
- pgvector 扩展用于未来 AI 功能

## 后果
- 需要管理架构迁移
- 可能需要只读副本来扩展
- 团队需要学习 Supabase 特定功能

组件文档

## 身份验证模块

### 概述
使用 JWT 令牌和刷新轮换处理用户身份验证。

### 流程
1. 用户提交凭据到 `/auth/login`
2. 服务器验证并返回访问和刷新令牌
3. 访问令牌用于 API 请求（15分钟有效期）
4. 刷新令牌用于获取新的访问令牌（7天有效期）

### 依赖
- `jsonwebtoken` - 令牌生成/验证
- `bcrypt` - 密码哈希
- `redis` - 刷新令牌存储

### 配置
- `JWT_SECRET` - 签名令牌的秘密
- `ACCESS_TOKEN_EXPIRY` - 访问令牌生命周期
- `REFRESH_TOKEN_EXPIRY` - 刷新令牌生命周期

文档原则

1. 为受众写作 - 新开发者 vs API 消费者
2. 保持靠近代码 - 文档在同一仓库中，靠近相关代码
3. 随代码更新 - 过时的文档比没有更糟
4. 示例优于解释 - 展示，而不仅仅是告诉
5. 渐进式披露 - 先快速开始，后细节