codebase-documenter

代码库文档编写

概述

此技能可帮助为代码库编写全面且适合初学者的文档。它提供结构化模板和最佳实践，用于编写 README、架构指南、代码注释和 API 文档，帮助新用户快速了解项目并参与贡献。

适合初学者的文档核心原则

为新用户编写代码文档时，请遵循以下基本原则：

1. 从“为什么”开始 - 深入实现细节之前，先说明目的
2. 循序渐进地呈现信息 - 按由简到繁的层次介绍信息
3. 提供背景信息 - 不仅要说明代码的功能，还要解释它存在的原因
4. 提供示例 - 为每个概念展示具体的用法示例
5. 假设读者没有相关基础知识 - 尽可能定义术语并避免行话
6. 使用视觉辅助材料 - 使用图表、流程图和文件树结构
7. 帮助用户快速上手 - 帮助用户在 5 分钟内运行起一些内容

文档类型及适用场景

1. README 文档

适用场景： 项目根目录、主要功能模块或独立组件。

建议结构：

# Project Name

## What This Does
[1-2 sentence plain-English explanation]

## Quick Start
[Get users running the project in < 5 minutes]

## Project Structure
[Visual file tree with explanations]

## Key Concepts
[Core concepts users need to understand]

## Common Tasks
[Step-by-step guides for frequent operations]

## Troubleshooting
[Common issues and solutions]

最佳实践：

• 开篇阐明项目的价值主张
• 提供确实可用的设置说明（请先测试！）
• 直观展示项目结构
• 链接到更深入的文档，供读者了解高级主题
• 让根目录的 README 专注于帮助用户快速上手

2. 架构文档

适用场景： 包含多个模块、复杂数据流或不明显设计决策的项目。

建议结构：

# Architecture Overview

## System Design
[High-level diagram and explanation]

## Directory Structure
[Detailed breakdown with purpose of each directory]

## Data Flow
[How data moves through the system]

## Key Design Decisions
[Why certain architectural choices were made]

## Module Dependencies
[How different parts interact]

## Extension Points
[Where and how to add new features]

最佳实践：

• 使用图表展示系统组件及其关系
• 解释架构决策背后的“为什么”
• 记录正常流程和错误处理方式
• 明确各模块的边界
• 添加带注释的可视化文件树结构

3. 代码注释

适用场景： 复杂逻辑、不明显的算法或需要背景信息的代码。

注释模式：

函数/方法文档：

/**
 * Calculates the prorated subscription cost for a partial billing period.
 *
 * Why this exists: Users can subscribe mid-month, so we need to charge
 * them only for the days remaining in the current billing cycle.
 *
 * @param {number} fullPrice - The normal monthly subscription price
 * @param {Date} startDate - When the user's subscription begins
 * @param {Date} periodEnd - End of the current billing period
 * @returns {number} The prorated amount to charge
 *
 * @example
 * // User subscribes on Jan 15, period ends Jan 31
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // Returns: 16.13 (17 days out of 31 days)
 */

复杂逻辑文档：

# Why this check exists: The API returns null for deleted users,
# but empty string for users who never set a name. We need to
# distinguish between these cases for the audit log.
if user_name is None:
    # User was deleted - log this as a security event
    log_deletion_event(user_id)
elif user_name == "":
    # User never completed onboarding - safe to skip
    continue

最佳实践：

• 解释“为什么”，而非“是什么”——代码已经展示了它的功能
• 记录边缘情况和业务逻辑
• 为复杂函数添加示例
• 解释含义不明确的参数
• 指出易出错之处或反直觉的行为

4. API 文档

适用场景： 所有 HTTP 端点、SDK 方法或公共接口。

建议结构：

## Endpoint Name

### What It Does
[Plain-English explanation of the endpoint's purpose]

### Endpoint
`POST /api/v1/resource`

### Authentication
[What auth is required and how to provide it]

### Request Format
[JSON schema or example request]

### Response Format
[JSON schema or example response]

### Example Usage
[Concrete example with curl/code]

### Common Errors
[Error codes and what they mean]

### Related Endpoints
[Links to related operations]

最佳实践：

• 提供可用的 curl 示例
• 展示成功和错误响应
• 清晰说明身份验证
• 记录速率限制和约束
• 为常见问题提供故障排查说明

文档工作流

第 1 步：分析代码库

编写文档之前：

1. 确定入口点 - 主文件、索引文件、应用初始化位置
2. 梳理依赖关系 - 各模块之间的关联方式
3. 找出核心概念 - 用户需要了解的关键抽象
4. 定位配置 - 环境设置、配置文件
5. 检查现有文档 - 在现有内容的基础上完善，不要重复编写

第 2 步：选择文档类型

根据用户请求和代码库分析结果：

• 新项目或缺少 README → 从 README 文档开始
• 架构复杂或包含多个模块 → 编写架构文档
• 代码段令人困惑 → 添加行内代码注释
• HTTP/API 端点 → 编写 API 文档
• 需要多种文档 → 按以下顺序处理：README → 架构 → API → 注释

第 3 步：生成文档

使用 assets/templates/ 中的模板作为起点：

• assets/templates/README.template.md - 用于项目 README
• assets/templates/ARCHITECTURE.template.md - 用于架构文档
• assets/templates/API.template.md - 用于 API 文档

根据特定代码库自定义模板：

1. 填写项目专属信息 - 将占位符替换为实际内容
2. 添加具体示例 - 使用项目中的真实代码
3. 加入可视化辅助内容 - 创建文件树、图表和流程图
4. 测试说明 - 验证设置步骤确实可行
5. 链接相关文档 - 将相关文档串联起来

第 4 步：检查清晰度

完成文档前：

1. 以初学者的视角阅读 - 不了解项目背景的人能看懂吗？
2. 检查完整性 - 说明中是否存在遗漏？
3. 验证示例 - 代码示例是否确实可运行？
4. 测试说明 - 其他人能否按照设置步骤操作？
5. 改进结构 - 信息是否易于查找？

文档模板

此技能在 assets/templates/ 中包含多个模板，提供了可供起步的结构：

可用模板

• README.template.md - 全面的 README 结构，包含快速入门、项目结构和常见任务等部分
• ARCHITECTURE.template.md - 架构文档模板，包含系统设计、数据流和设计决策
• API.template.md - API 端点文档，包含请求/响应格式和示例
• CODE_COMMENTS.template.md - 有效行内文档的示例和模式

使用模板

1. 阅读合适的模板，模板位于 assets/templates/
2. 根据具体项目自定义 - 将占位符替换为实际信息
3. 添加项目专属章节 - 根据需要扩展模板
4. 加入真实示例 - 使用代码库中的实际代码
5. 删除不相关章节 - 删除不适用的部分

最佳实践参考

如需了解详细的文档最佳实践、风格指南和高级模式，请参阅：

• references/documentation_guidelines.md - 全面的风格指南和最佳实践
• references/visual_aids_guide.md - 如何创建有效的图表和文件树

在以下情况下加载这些参考资料：

• 为复杂的企业级代码库编写文档
• 需要满足多个利益相关方的要求
• 需要使用高级文档模式
• 在大型项目中统一文档规范

常见模式

创建文件树结构

文件树可帮助新用户了解项目组织结构：

project-root/
├── src/                    # Source code
│   ├── components/        # Reusable UI components
│   ├── pages/             # Page-level components (routing)
│   ├── services/          # Business logic and API calls
│   ├── utils/             # Helper functions
│   └── types/             # TypeScript type definitions
├── public/                # Static assets (images, fonts)
├── tests/                 # Test files mirroring src structure
└── package.json           # Dependencies and scripts

说明复杂的数据流

使用带图表的编号步骤：

User Request Flow:
1. User submits form → 2. Validation → 3. API call → 4. Database → 5. Response

[1] components/UserForm.tsx
    ↓ validates input
[2] services/validation.ts
    ↓ sends to API
[3] services/api.ts
    ↓ queries database
[4] Database (PostgreSQL)
    ↓ returns data
[5] components/UserForm.tsx (updates UI)

记录设计决策

记录架构选择背后的“原因”：

## Why We Use Redux

**Decision:** State management with Redux instead of Context API

**Context:** Our app has 50+ components that need access to user
authentication state, shopping cart, and UI preferences.

**Reasoning:**
- Context API causes unnecessary re-renders with this many components
- Redux DevTools helps debug complex state changes
- Team has existing Redux expertise

**Trade-offs:**
- More boilerplate code
- Steeper learning curve for new developers
- Worth it for: performance, debugging, team familiarity

输出指南

生成文档时：

1. 面向目标受众撰写 - 根据文档面向初学者、中级用户还是高级用户调整复杂度
2. 使用一致的格式 - 遵循 Markdown 规范，保持标题层级一致
3. 提供可运行的示例 - 测试所有代码片段和命令
4. 关联各份文档 - 创建文档导航结构
5. 便于维护 - 随着代码变更，文档也应易于更新
6. 添加日期和版本 - 注明文档的最后更新时间

快速参考

生成 README 的命令：
“为此项目创建一个 README 文件，帮助新开发者快速上手”

编写架构文档的命令：
“编写此代码库的架构文档，说明不同模块之间如何交互”

添加代码注释的命令：
“为此文件添加说明性注释，帮助新开发者理解其中的逻辑”

编写 API 文档的命令：
“为此文件中的所有端点创建 API 文档”