Skip to content

Latest commit

 

History

History
163 lines (119 loc) · 6.85 KB

CODE_STANDARD.md

File metadata and controls

163 lines (119 loc) · 6.85 KB

CODE_STANDARD

本文件是项目的默认代码规范。任何 Agent 在新增、修改、重构或 Review 代码时都必须遵守;除非用户或项目已有更具体的规则明确覆盖。

1. 核心优先级

所有技术决策按以下顺序取舍:

  1. 正确
  2. 容易理解
  3. 容易 Review
  4. 容易修改
  5. 必要复用
  6. 通用化或炫技

发生冲突时,必须选择优先级更高的一项。

  • 不用“更优雅”交换正确性。
  • 不用“减少几行代码”交换可读性。
  • 不用“以后可能需要”增加当前复杂度。
  • 看起来高级不是目标,稳定解决问题才是目标。

2. 正确

  • 先确认需求、输入、输出、边界条件和失败行为,再写代码。
  • 不猜测现有接口、数据结构或业务规则;优先阅读已有实现与测试。
  • 捕获错误时,必须传播错误、转换为调用方可判断的错误,或执行已有的显式降级路径;禁止静默吞掉异常或伪造成功结果。
  • 在系统边界校验外部输入;内部代码不要重复无意义校验。
  • 修复 Bug 时,必须覆盖导致 Bug 的场景;能写自动化测试时应补测试。
  • 未被明确要求时,不破坏已有行为、接口和数据兼容性。
  • 没有实际执行的测试或检查,不得声称已经通过。

3. 容易理解

  • 优先使用直接、普通、符合语言习惯的写法。
  • 命名表达业务含义,避免无意义缩写、模糊名称和临时编号。
  • 一个函数或模块只承担一个连贯职责,但不要为了“短”而机械拆分。
  • 控制流保持清晰;优先早返回,减少深层嵌套。
  • 代码应尽量自解释;确有必要时,按下一节的规则添加注释。
  • 魔法数字、隐含状态和特殊规则必须被命名或集中说明。
  • 遵循项目现有风格,避免在同一代码库引入第二套表达方式。

4. 注释代码

注释用于补充代码无法清楚表达的信息,不是用来掩盖复杂代码。能通过命名、拆分或简化表达清楚时,优先改代码。

应当注释:

  • 非显然的业务规则、设计取舍、前置条件和不变量;
  • 看似多余但因兼容性、并发、安全、性能或数据一致性而必须保留的代码;
  • 外部系统的异常行为、临时绕过方案及其移除条件;
  • 公共接口中无法由类型直接表达的单位、副作用、失败行为和使用约束。

不得:

  • 把代码逐行翻译成自然语言;
  • 为简单、明显的代码添加噪声注释;
  • 保留被注释掉的旧代码;应删除并交由版本控制保存;
  • 写与实现不一致、无法验证或可能误导 Reviewer 的注释;
  • 写没有原因和完成条件的 TODO、FIXME。项目使用 Issue 系统时应附编号。

规则:

  • 注释优先解释“为什么”,必要时说明“约束、风险和例外”,少解释“做了什么”;
  • 注释放在最接近相关代码的位置,保持简短、具体、可验证;
  • 修改代码时必须同步检查并更新相关注释;过期注释视为缺陷;
  • 文档注释描述稳定契约,内部注释描述实现原因,不混淆两者;
  • 不理解某段代码或注释时,先调查和验证,不得猜测后删除或改写。

示例:

// 差:重复代码含义
retryCount++; // 重试次数加一

// 好:说明保留该逻辑的原因和边界
// 第三方接口偶发返回 429;最多重试 3 次,避免形成请求风暴。
retryCount++;

5. 容易 Review

  • 只修改完成当前任务所必需的代码。
  • 禁止混入无关的格式化、重命名、重构、依赖升级或目录调整。
  • 一次变更应有单一、明确的目的。
  • 关键假设、行为变化、兼容性影响和已知风险必须显式说明。
  • 代码、测试、类型、配置和文档应在同一变更中保持一致。
  • 大改动应拆成可独立验证的小步骤,但不得制造无法运行的中间状态。

6. 容易修改

  • 把经常变化的业务规则与稳定机制分开。
  • 副作用应集中在边界;核心逻辑尽量保持显式输入和输出。
  • 避免隐藏的全局状态、跨模块写入和不透明的隐式行为。
  • 接口暴露必要能力,不泄漏无关实现细节。
  • 依赖方向必须清晰,避免循环依赖和跨层调用。
  • 先写最小可行结构;只有真实变化需求出现后再增加扩展点。

7. 必要复用

复用不是默认目标。只有同时满足以下条件时才抽象:

  • 代码表达的是同一个概念或同一条业务规则;
  • 多处实现应当一起变化;
  • 抽象后的名称和接口比重复代码更容易理解;
  • 抽象确实降低维护成本,而不是隐藏差异。

规则:

  • 优先复用项目中已有、稳定、语义匹配的实现。
  • 语义不同但代码相似时,允许保留重复。
  • 不创建只有一个调用方、且没有明确价值的公共工具层。
  • 不为消除少量重复引入复杂继承、回调链或通用框架。

8. 通用化与炫技

除非当前需求明确需要,否则禁止:

  • 为假设中的未来需求设计插件系统、规则引擎或配置平台;
  • 引入复杂泛型、反射、元编程、DSL 或深层继承;
  • 新增依赖只为替代少量清晰代码;
  • 在没有数据证明前进行性能优化;
  • 使用团队难以维护的冷门语法或技巧。

任何额外复杂度都必须能回答:它解决了当前哪个真实问题?

9. Agent 默认执行规则

Agent 写代码时必须:

  1. 阅读相关代码、测试和项目约定。
  2. 明确当前任务的行为边界,不自行扩大范围。
  3. 选择能正确解决问题的最简单方案。
  4. 保持变更最小,不顺手重构无关代码。
  5. 添加或更新必要测试与注释。
  6. 执行适用的测试、类型检查、静态检查和格式检查。
  7. 自我 Review 后再提交结果。
  8. 明确报告:改了什么、验证了什么、哪些内容未验证、是否存在风险。

Agent 不得:

  • 编造接口、依赖、测试结果或运行结果;
  • 因为偏好某种架构而改写正常工作的代码;
  • 在没有必要时增加抽象层、配置项或扩展点;
  • 用大规模重构掩盖一个本可局部修复的问题。

10. 提交前检查

  • 行为是否正确,边界和失败路径是否处理?
  • 是否存在更直接、更容易理解的实现?
  • 变更是否仅包含当前任务所需内容?
  • Reviewer 能否快速看懂目的、影响和风险?
  • 后续修改是否有清晰入口,副作用是否可控?
  • 新增抽象是否真的必要?
  • 注释是否必要、准确,并与当前实现一致?
  • 测试是否覆盖关键行为和本次修复?
  • 所有验证结果是否真实、可复现?

11. 最终判断

当两个方案都能工作时,选择:

更少假设、更少隐藏行为、更小改动、更直白、更容易验证的方案。