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

3.9 KiB
Raw Blame History

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。

不要做的事

  • 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
  • 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
  • 不要在功能 PR 里顺手重构无关代码。开新 PR。
  • 不要没量就先优化。"可能慢"不是测量结果。