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>
3.9 KiB
3.9 KiB
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。按这个顺序回答:
- 这是什么? 一段话。
- 怎么跑? Setup / run / test 的 bash 块。
- 怎么开发? 代码在哪,约定是什么。
- 数据从哪来 / 去哪? 仅当不显然才写。
- 指针。 关联仓库、dashboard、文档。
用 templates/README.md.template。如果你的 README 比模板短,没问题
——把没用的 section 删掉。
交付物(任务包、数据集、导出)
给伙伴或下游交付时:
- 文件名带版本:
<name>-v<n>.<ext>或<name>-<YYYYMMDD>.<ext>。 一个项目一种约定,定了别变。 - 配
README写明 schema、生成日期、已知限制。 - 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。
- 生成它的 commit hash 写进 README。
完整 checklist 见 docs/06-handoff.md。
不要做的事
- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
- 不要在功能 PR 里顺手重构无关代码。开新 PR。
- 不要没量就先优化。"可能慢"不是测量结果。