代码评审规范

Code Review（代码评审）不能是流于形式的走个过场 “一键 Approve”，也不会是针对个人的挑刺会。

它是拦截低级 Bug 流入生产环境的最后一道防线，更是团队内部技术对齐、消除技术债最有效的常态化机制。

一次好的 Code Review 能够：

• 在问题进入主干前拦截 Bug 和设计缺陷
• 传递代码知识，让团队对业务和技术保持底层共识
• 推动规范常态化落地，形成统一的代码风格
• 降低新成员熟悉代码库的成本与劝退率

提交前自查

在发起 Pull Request 之前，作者应先完成自查，避免把低级问题留给 Reviewer。

提交前清单

• 本地编译 100% 通过，无报错、无警告
• 所有改动与 PR 描述严格一致，无多余文件
• 新增的公开 API、复杂逻辑、特殊兼容已添加注释
• 涉及核心接口变更，已同步更新调用方

PR 提交者规范

PR 粒度

核心原则：一个 PR 只做一件事。

禁止大体量 PR

不要将多个不相关的功能或修复等，混在同一个 PR 中提交。

大 PR 的危害：

• Reviewer 无法在合理时间内完成审查
• 合并冲突概率大幅上升
• 回滚成本极高，可能无法精准还原

PR 粒度参考：

类型	建议粒度
新功能	按最小可交付单元拆分，每个 PR 对应一个完整的小功能
Bug 修复	一个 PR 只修一个 Bug
重构	与业务改动分开提交，纯重构单独一个 PR
依赖升级	单独一个 PR，附上变更说明

PR 描述

PR 描述是 Reviewer 理解改动背景的第一入口，不能只写 "fix bug" 等无意义字符，更严禁留空。

推荐格式：详见 Commit 提交规范

提炼重点

描述不需要面面俱到，但至少要让 Reviewer 在没有额外沟通的情况下，理解这个 PR 在解决什么问题。

Review 审查者规范

Reviewer 职责

Reviewer 的核心职责应是保证代码质量，而不是一味查验代码与自己风格是否一致。

Reviewer 的核心职责应是捍卫主干代码的健壮性与架构秩序，而非一味查验代码风格是否与个人的主观偏好绝对一致。

审查时重点关注

• 正确性：逻辑是否存在隐藏 Bug？，临界状态、边界条件是否做好了兜底处理？
• 可维护性：职责是否清晰？是否违反单一职责原则？是否无端引入了不必要的隐性复杂度？
• 规范符合度：命名是否语义化？是否严格遵循了本团队的规范？
• 性能：是否存在明显的性能问题？（如：主线程耗时、内存泄漏）

对于纯粹的个人习惯偏好（例如使用 Kotlin 语法糖的微小差异），只要符合现有规范，Reviewer 应保持技术包容。

意见定级

Reviewer 提交评论时必须明确带有统一的级别前缀，表明该意见的严重程度：

级别前缀	含义说明	是否阻断合并	典型场景
[BLOCK]	阻断级问题	是	存在明确 Bug 或严重设计问题、或严重违背核心架构职责。
[WARN]	警告级建议	否	命名语义不够清晰、方法体积微大、缺乏必要的关键行背景注释、或存在更优雅的替代方案。
[QUS]	疑问澄清	否	代码逻辑过于晦涩，Reviewer 无法直接看懂，需要 Author 解释设计意图。
[NIT]	琐碎细节	否	错别字、多余的空行或空格、漏掉的换行等无伤大雅的排版问题。

示例：

评论语气

评论要对事不对人，保持冷峻、专业客观的描述问题，而不是指责人。

好的评论示例：

[BLOCK]：这里如果 `list` 为空会抛 `IndexOutOfBoundsException`，建议加一个边界判断。

[WARN]：这个方法现在承担了两个职责，建议拆开，方便后续单独测试。

[BLOCK]：这里用 `GlobalScope` 会导致协程在 Activity 销毁后仍然运行，建议改用 `viewModelScope`。

避免的评论方式

• "这段代码写得很烂。"（带有攻击性，毫无工程建设性）
• "你为什么要这样写？"（质问语气，应改为提问 + 建议）
• "这完全不对，去改掉。"（没有说明哪里不对，没有指引修改方向）

高频问题清单

这是 Review 中频繁出现的问题黑榜，Author 在提交前应重点自查。

展开查看高频雷区

内存与生命周期

• 非静态内部类或匿名类是否持有外部 Activity/Fragment 引用
• Handler / Runnable 是否在 onDestroy 中移除
• LiveData / StateFlow 观察者是否使用 viewLifecycleOwner
• ViewModel 是否持有 Context 或 View 引用

线程安全

• 数据库、文件 IO、等耗时操作是否在主线程执行
• 多线程访问的共享变量是否有适当的同步保护
• GlobalScope 是否被滥用

空安全

• 可空返回值是否有判空处理
• 强制 !! 断言非空是否有充分理由
• @Nullable / @NonNull 注解是否与实现一致

代码质量

• 是否存在重复逻辑，可以抽取公共方法
• 方法是否过于庞大，是否需要拆分
• 命名是否符合语义化规范
• 异常是否被静默吞掉

总结

Code Review 的价值在于持续。一次认真的 Review 能拦截 Bug，百次认真的 Review 能拉高并稳固整个团队的代码质量下限。

• 作为 Author，把 PR 写清楚是对 Reviewer 时间的尊重。
• 作为 Reviewer，把问题说清楚是对团队代码库的负责。