# 文档编写规则

## 你必须遵守的文档原则

### 1. 清晰性原则（必须遵守）

**文档要求：**

- **必须**：文档应该清晰、准确
- **必须**：使用简单的语言
- **必须**：避免不必要的技术术语
- **必须**：必要时提供术语解释

**写作要求：**

- 使用短句，避免长句
- 使用主动语态
- 使用具体的例子
- 避免模糊的表达

### 2. 完整性原则（必须遵守）

**文档要求：**

- **必须**：文档应该覆盖所有重要功能
- **必须**：包含使用示例
- **必须**：说明限制和注意事项
- **必须**：说明前提条件和依赖

**内容要求：**

- 功能描述：说明功能做什么
- 使用方法：说明如何使用
- 参数说明：说明所有参数
- 返回值说明：说明返回值
- 异常说明：说明可能抛出的异常
- 示例代码：提供可运行的示例

### 3. 及时性原则（必须遵守）

**维护要求：**

- **必须**：代码变更时同步更新文档
- **必须**：文档应该反映当前实现
- **必须**：删除过时的文档
- **禁止**：文档与代码不一致

**更新时机：**

- 添加新功能时，立即更新文档
- 修改功能时，同步更新文档
- 删除功能时，删除相关文档
- 定期检查文档与代码的一致性

## 你必须编写的文档类型

### 1. 代码注释（必须编写）

**注释要求：**

- **必须**：解释"为什么"，而不是"做什么"
- **必须**：复杂逻辑必须有注释
- **必须**：公共 API 必须有文档字符串
- **禁止**：注释重复代码内容

**注释内容：**

- 业务逻辑说明
- 算法选择原因
- 特殊处理的原因
- 已知问题和限制

**文档字符串格式：**

```python
def calculate_total(items: list[Item], discount: float = 0.0) -> float:
    """计算商品总价

    参数:
        items: 商品列表，不能为空
        discount: 折扣率，范围 0.0-1.0，默认 0.0

    返回:
        计算后的总价，已应用折扣

    异常:
        ValueError: 当 items 为空或 discount 不在有效范围时抛出

    示例:
        >>> items = [Item(price=10.0), Item(price=20.0)]
        >>> calculate_total(items, discount=0.1)
        27.0
    """
    pass
```

### 2. README 文档（必须编写）

**README 要求：**

- **必须**：项目概述和快速开始
- **必须**：安装和配置说明
- **必须**：使用示例
- **必须**：常见问题解答（如适用）

**README 结构：**

- 项目简介
- 功能特性
- 安装步骤
- 配置说明
- 快速开始
- 使用示例
- API 文档链接
- 贡献指南
- 许可证信息

### 3. API 文档（必须编写）

**API 文档要求：**

- **必须**：函数签名和参数说明
- **必须**：返回值说明
- **必须**：使用示例
- **必须**：异常说明

**文档内容：**

- 函数/方法签名
- 参数类型和说明
- 返回值类型和说明
- 可能抛出的异常
- 使用示例
- 相关 API 链接

## 文档编写检查清单

在完成代码后，你必须确认：

**代码注释：**

- [ ] 所有公共 API 都有文档字符串
- [ ] 复杂逻辑有注释说明
- [ ] 注释解释了"为什么"而非"做什么"
- [ ] 没有过时的注释

**README：**

- [ ] README 包含快速开始指南
- [ ] 有安装和配置说明
- [ ] 有使用示例
- [ ] 文档清晰、易读

**API 文档：**

- [ ] 所有公共 API 都有文档
- [ ] 参数和返回值都有说明
- [ ] 有使用示例
- [ ] 说明了可能抛出的异常

**文档维护：**

- [ ] 文档与代码保持同步
- [ ] 删除了过时的文档
- [ ] 文档反映了当前实现
