跳到主要内容

代码与评审规范

代码是给「半年后的自己和下一棒」看的。
本章约定日常开发与合并的默认纪律。

1. 代码风格（通用）​

  • 命名：见名知意；避免拼音无序缩写与魔法数字
  • 函数/模块：单一职责；过长先拆再提审
  • 错误处理：不吞错；错误信息要能定位
  • 日志：关键路径可追踪；禁止明文敏感信息（手机号、证件、密钥等）
  • 注释：写「为什么」，少写「做了什么」（代码本身应可读）

语言相关细则（Go 等）可在语言教程中补充；冲突时以可维护与团队一致为准。

2. 提交（Commit）​

建议：

  • 一次提交只做一类改动
  • 说明写清「改了什么 / 为什么」
  • 不提交本地机密、大文件、生成物（除非仓库明确需要）

示例：

fix(order): 防止并发退款超额

退款路径加事务与状态守卫，并补回归用例。

3. 分支与合并​

推荐主干 + 短生命周期特性分支：

  1. 从主分支拉出特性分支
  2. 小步提交，保持可编译/可测
  3. 发起评审（MR/PR）
  4. 通过门禁后合并
  5. 删除已合并分支

热修走约定热修流程，合并后仍须补评审与记录。

4. 评审清单（Reviewer）​

评审至少关注：

  • 是否符合范围与边界（有无偷偷改契约）
  • 主路径与关键异常是否合理
  • 权限与数据暴露是否安全
  • 是否有明显性能雷（N+1、无界查询、同步大导出）
  • 测试/验证步骤是否足够
  • 日志与可观测是否够用
  • 文档/配置说明是否要同步改

评审意见对事不对人；阻断项与建议项分开说。

5. 作者在提审前自检​

  • 本地主路径验证过
  • 自测说明写在 MR 描述里
  • 无调试代码、无临时开关残留（除非有意保留并说明）
  • 需要迁移/配置时，步骤写清楚

6. 与完成定义的关系​

合并进主线 ≠ 项目完成。
上线与交接仍须满足 完成定义。

接口变更另见 API 设计边界。