Back to Details

code-discipline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Discipline

代码规范

Rules for writing clean, minimal, production-grade code. These apply to every code change — no exceptions.
编写精简、清晰、生产级代码的规则。这些规则适用于每一次代码变更，没有例外。

1. Change Only What's Asked

1. 仅修改需求涉及的内容

Touch only the code necessary to complete the request. Do not:
  • Refactor surrounding code that "could be better"
  • Add docstrings, type annotations, or comments to untouched code
  • Rename variables you didn't introduce
  • "Improve" imports, formatting, or style outside your change
If existing code has problems, mention them — don't fix them silently.
只触碰完成需求所需的代码。请勿：
  • 重构周边“本可以更好”的代码
  • 给未改动的代码添加文档字符串、类型注解或注释
  • 重命名不是你引入的变量
  • “优化”你的变更范围之外的导入语句、格式或代码风格
如果现有代码存在问题，请提及它们，不要默默修复。

2. No Speculative Code

2. 不要编写推测性代码

Write code for current requirements, not hypothetical futures. Do not:
  • Add error handling for scenarios that cannot occur
  • Build abstractions for a single use case
  • Add feature flags, configuration options, or extension points that weren't asked for
  • Create helper functions for one-time operations
  • Add backwards-compatibility shims when you can just change the code
Three similar lines of code are better than a premature abstraction.
围绕当前需求编写代码，而不是假设的未来需求。请勿：
  • 为不可能发生的场景添加错误处理
  • 为单一使用场景构建抽象
  • 添加未被要求的功能开关、配置选项或扩展点
  • 为一次性操作创建辅助函数
  • 当你可以直接修改代码时，反而添加向后兼容垫片
三行功能相似的代码也好过过早的抽象。

3. Match Existing Patterns

3. 匹配现有模式

Before proposing any change, read the files you intend to modify. Then:
  • Match existing naming conventions (camelCase, snake_case, etc.)
  • Follow established code organization and file structure
  • Use the same patterns for similar operations — do not introduce a new style
  • Adopt the project's existing approach to error handling, logging, and testing
When in doubt, imitate what's already there.
在提出任何变更前，先阅读你打算修改的文件。然后：
  • 匹配现有的命名规范（camelCase、snake_case等）
  • 遵循已有的代码组织和文件结构
  • 相似操作使用相同的模式，不要引入新的风格
  • 采用项目现有的错误处理、日志和测试方案
拿不准的时候，模仿已有的代码写法。

4. Delete Completely

4. 完全删除废弃代码

When removing code, remove it. Do not:
  • Comment it out
  • Rename unused variables with a 
    _
    prefix
  • Add 
    // removed
    or 
    // deprecated
    markers
  • Re-export removed items for backwards compatibility
  • Leave empty blocks or placeholder comments
If you're certain something is unused, delete it entirely.
移除代码的时候就彻底删掉。请勿：
  • 把代码注释掉
  • 给未使用的变量加上
    _
    前缀重命名
  • 添加
    // removed
    或
    // deprecated
    标记
  • 为了向后兼容重新导出已经移除的内容
  • 留下空代码块或者占位注释
如果你确定某部分代码没有被使用，就完全删除它。

5. Comments Explain Why

5. 注释解释原因

Only add comments where the logic isn't self-evident. Comments must explain why, not what. Do not add:
  • Comments that restate the code (
    // increment counter
    )
  • Temporal markers (
    // added in v2
    , 
    // phase 1
    )
  • AI attribution (
    // generated by Claude
    )
  • Section dividers or decorative comments
  • TODO comments unless the user asked for them
No comment is better than a redundant comment.
仅在逻辑并非不言自明的地方添加注释。注释必须解释为什么这么做，而不是解释做了什么。请勿添加：
  • 复述代码内容的注释（
    // increment counter
    ）
  • 时间标记（
    // added in v2
    、
    // phase 1
    ）
  • AI归属标记（
    // generated by Claude
    ）
  • 章节分隔符或者装饰性注释
  • TODO注释，除非用户明确要求添加
没有注释也好过冗余的注释。

6. Clarity Over Cleverness

6. 清晰优先于巧妙

Write code that reads naturally. Prefer:
  • Explicit logic over compact one-liners
  • Named variables over inline expressions
  • Early returns over deep nesting
  • Simple conditionals over nested ternaries
If a reader needs to pause to parse it, rewrite it more clearly.
编写读起来自然的代码。优先选择：
  • 显式逻辑而非紧凑的单行代码
  • 具名变量而非内联表达式
  • 提前返回而非深层嵌套
  • 简单的条件判断而非嵌套的三元表达式
如果读者需要停下来思考才能理解代码，就把它改得更清晰一点。

7. Validate at Boundaries

7. 在边界处做校验

Handle errors where untrusted data enters your system:
  • User input, API responses, file I/O, environment variables
Trust internal code and framework guarantees. Do not:
  • Defensively null-check values that are never null
  • Wrap internal calls in try/catch "just in case"
  • Validate function arguments from your own codebase
  • Add fallback defaults for values guaranteed by the type system
在不受信任的数据进入系统的位置处理错误：
  • 用户输入、API响应、文件I/O、环境变量
信任内部代码和框架的保证。请勿：
  • 对永远不会为null的值做防御性空校验
  • “以防万一”给内部调用套上try/catch
  • 校验来自你自己代码库的函数参数
  • 为类型系统保证存在的值添加回退默认值

8. Verify Your Work

8. 验证你的工作

After implementation, run the existing test suite. Do not assume tests pass. If tests break, fix them before moving on. If there is no test suite, check that the code at least compiles/parses without errors.
实现完成后，运行现有的测试套件。不要假设测试能通过。如果测试失败，先修复它们再继续。如果没有测试套件，至少检查代码可以无错误编译/解析。

Per-Change Checklist

每次变更检查清单

Before finishing any code change, verify:
  • Every modified line is necessary for the request
  • No speculative features, abstractions, or error handling was added
  • Existing code style and conventions are matched
  • Removed code is fully deleted, not commented out
  • Comments (if any) explain why, not what
  • Code reads clearly without requiring mental gymnastics
  • Error handling is only at system boundaries
  • Tests pass (or code compiles if no tests exist)
For concrete examples of these principles, read 
references/examples.md
.
完成任何代码变更前，请确认：
  • 每一行修改的代码都是完成需求所必需的
  • 没有添加推测性的功能、抽象或错误处理
  • 匹配了现有的代码风格和规范
  • 移除的代码已被完全删除，而非注释掉
  • 注释（如果有）解释了原因，而非做了什么
  • 代码读起来清晰易懂，不需要耗费脑力理解
  • 仅在系统边界处做错误处理
  • 测试通过（如果没有测试则代码可正常编译）
如需了解这些原则的具体示例，请阅读
references/examples.md
。