Files
praxis/docs/05-code-style.md
T
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
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>
2026-05-20 09:44:15 +08:00

97 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。
- 不要没量就先优化。"可能慢"不是测量结果。