# 02 · 代码标准

> **目标**:让人和 AI 写出的代码风格一致、可读、可测、可维护。CI 会自动检查其中可机检的部分。

---

## 1. 格式与静态检查

- Python 项目推荐:`ruff format .` + `ruff check .`。
- 其他语言按项目技术栈替换为对应工具,例如 ESLint/Prettier、Checkstyle、gofmt。
- 行宽默认 100;缩进、import 分组、命名风格由工具强制。
- 提交前本地必须通过格式与 lint;CI 会再卡一道。

## 2. 命名

| 对象 | 推荐规则 | 示例 |
|---|---|---|
| 变量/函数 | `snake_case` | `load_config` |
| 类 | `PascalCase` | `UserService` |
| 常量 | `UPPER_SNAKE` | `DEFAULT_PORT` |
| 私有实现 | 前缀 `_` | `_parse_row` |

命名必须表达意图。禁止 `process2`、`new_func`、`tmp_final` 这类无法审查的名字。

## 3. 函数与模块

- 一个函数只做一件事;超过约 40 行优先拆分。
- 参数过多时使用配置对象/数据类。
- 业务逻辑与 I/O 分离,核心逻辑优先写成纯函数,方便测试。
- 新增目录或模块前,先确认能落进 `00-project-context.md` 的目录地图。

## 4. 注释

- 不写废话注释,例如 `# 调用函数` 配 `call_func()`。
- 注释只解释“为什么”和“权衡”,不重复“代码做了什么”。
- 复杂业务规则、部署坑、兼容性原因必须写清楚。

## 5. 配置与密钥

- 非敏感配置可进 Git,例如 `config.yaml`、`.env.example`。
- 密钥、密码、Token、私钥绝不进 Git,只放 GitHub Secrets / 环境变量。
- 代码读取密钥时使用环境变量,并在 README 写清变量名,不写真实值。

## 6. 错误处理

- 禁止裸 `except: pass`。
- 外部输入必须校验,错误信息要能帮助定位。
- 部署脚本必须失败即停;不能让前一步失败后继续执行后续危险动作。

## 7. 提交前自检

```text
[ ] 格式检查通过
[ ] 静态检查通过
[ ] 新增逻辑有测试
[ ] 没有硬编码密钥
[ ] 没有调试 print / 死代码 / 大段注释代码
[ ] 目录结构仍符合 00-project-context.md
```