# 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. 文件名带版本:`-v.` 或 `-.`。 一个项目一种约定,定了别变。 2. 配 `README` 写明 schema、生成日期、已知限制。 3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。 4. 生成它的 commit hash 写进 README。 完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。 ## 不要做的事 - 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。 - 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。 - 不要在功能 PR 里顺手重构无关代码。开新 PR。 - 不要没量就先优化。"可能慢"不是测量结果。