Language policy: Chinese for human-facing files (README, docs/, human-fillable templates), English for AI-facing files (CLAUDE.md, AGENTS.md, AI templates). Commits / PRs / branches / tags stay English. - Translate docs/01-06 to Chinese - Translate README.md, PR / handoff / project README templates to Chinese - Drop README.en.md (redundant once language policy is explicit) - Rewrite CLAUDE.md and CLAUDE.md.template under the new policy - Add AGENTS.md (root) and templates/AGENTS.md.template for Codex - Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 05 — 代码与产出风格
|
||
|
||
命名、注释、结构。不论是人写的还是 AI 写的代码,都按这套来。
|
||
|
||
## 命名
|
||
|
||
- **文件** —— 小写。文档用连字符(`git-workflow.md`),Python 用
|
||
下划线(`task_runner.py`),JS/TS 跟生态走 kebab。匹配周围项目。
|
||
- **函数** —— 动词短语。`loadConfig` 不是 `config`;`runTask`
|
||
不是 `taskRunner`。
|
||
- **变量** —— 写它**是什么**,不写它的类型。`users` 不是
|
||
`userArray`;`retryCount` 不是 `n`。
|
||
- **布尔** —— `is*`、`has*`、`should*`。`isReady` 不是 `ready`。
|
||
- **常量** —— `UPPER_SNAKE_CASE` 仅用于真正的模块级常量。函数内用
|
||
普通 `const`。
|
||
- **不要缩写**——除非是领域术语。`database` 不是 `db`,`request`
|
||
不是 `req`。(Express handler 里的 `req`/`res` 是领域约定,可以。)
|
||
|
||
## 注释
|
||
|
||
默认不写。要写注释,**全部**条件成立:
|
||
|
||
- "为什么"从代码里看不出来。
|
||
- 未来读代码的人不写注释会读错。
|
||
- 代码本身改不清晰(重命名、抽函数、重组都试过)。
|
||
|
||
不要写:
|
||
|
||
- `// increment counter` 紧挨着 `counter++`
|
||
- `// added for the auth refactor` —— 这话该在 commit message 里
|
||
- 一大段 docstring 只是把签名复述一遍
|
||
- 没有 owner 没有日期的 TODO —— 它们会烂掉。要么现在修,要么开
|
||
issue,要么删了。
|
||
|
||
可以写:
|
||
|
||
- 一行解释一个非显而易见的 workaround,带上**为什么**。
|
||
- `# NOTE:` 标注会让读者意外的行为。
|
||
- 文件头注释,仅限于这个文件做的事目录结构没说清楚。
|
||
|
||
## 文件结构
|
||
|
||
- 一个文件一个概念。一句话说不清这个文件干啥——拆。
|
||
- 测试文件挨着代码放,除非项目本来就是平行测试树。
|
||
- 生成文件进 `dist/` / `build/` 这类目录,进 `.gitignore`。永远
|
||
不改生成文件。
|
||
- Lockfile 必须 commit,永远。
|
||
|
||
## 错误
|
||
|
||
- 在边界处(用户输入、外部 API、文件 I/O)大声失败。
|
||
- 不要 `try/except` 吞错。捕了就处理。
|
||
- 内部函数信任调用方,不要在三层深度上重复校验同一个输入。
|
||
- 日志里的错要带够上下文,光看日志能调试——做的什么操作、输入是
|
||
什么、走的哪条路径。
|
||
|
||
## 测试
|
||
|
||
- 测行为,不测实现。一个保留行为的重构把测试搞挂了——是测试错。
|
||
- 一个测试一个断言为佳。"啥都测的测试,挂了你不知道是哪一个挂了。"
|
||
- Fixture 和用它的测试放一起。
|
||
- 慢 / flaky 的测试加标记或隔离,不要默默重试。
|
||
- 没测试的新代码就是没写完——除非项目真的没有测试基础设施
|
||
(罕见,而且这本身是个 bug)。
|
||
|
||
## README
|
||
|
||
每个仓库都要有 `README.md`。按这个顺序回答:
|
||
|
||
1. **这是什么?** 一段话。
|
||
2. **怎么跑?** Setup / run / test 的 bash 块。
|
||
3. **怎么开发?** 代码在哪,约定是什么。
|
||
4. **数据从哪来 / 去哪?** 仅当不显然才写。
|
||
5. **指针。** 关联仓库、dashboard、文档。
|
||
|
||
用 `templates/README.md.template`。如果你的 README 比模板短,没问题
|
||
——把没用的 section 删掉。
|
||
|
||
## 交付物(任务包、数据集、导出)
|
||
|
||
给伙伴或下游交付时:
|
||
|
||
1. 文件名带版本:`<name>-v<n>.<ext>` 或 `<name>-<YYYYMMDD>.<ext>`。
|
||
一个项目一种约定,定了别变。
|
||
2. 配 `README` 写明 schema、生成日期、已知限制。
|
||
3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。
|
||
4. 生成它的 commit hash 写进 README。
|
||
|
||
完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。
|
||
|
||
## 不要做的事
|
||
|
||
- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
|
||
- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
|
||
- 不要在功能 PR 里顺手重构无关代码。开新 PR。
|
||
- 不要没量就先优化。"可能慢"不是测量结果。
|