Code Review & 开发行为规范

目录

• 概述与核心理念
• 代码开发与实现规范
  • 命名约定
  • 代码编写原则
  • 注释规范
• 异常处理规范
• 日志管理规范
• 版本控制与协作规范（Git）
  • Git 分支策略
  • 代码提交与审核
  • 标签（Tag）管理
• 常见代码“坏味道”与优化建议

概述与核心理念

本规范旨在建立一套行之有效的研发行为准则，以指导团队构建高质量、可维护、可扩展的软件产品，并提升团队协作效率。我们深知在软件的全生命周期中，维护成本占据主导地位，因此，所有规范的制定都围绕“降低维护成本，提高交付效率”这一核心目标展开。

核心指导原则：
• 业务价值优先：所有技术实现都应紧密围绕商业业务需求，为业务创造价值。
• 快速迭代与适应性：设计和实现应充分考虑业务的快速变化，具备良好的可拓展性和可配置性，支持快速迭代。
• 团队协作与规范统一：建立统一的协作约束和规范，确保团队成员高效协作，减少沟通成本和集成风险。
• 代码质量与可维护性：追求代码的清晰、简洁、健壮，确保软件长期稳定运行，降低后续维护和功能拓展的难度。

代码开发与实现规范

本节详细阐述在代码编写层面的具体要求，旨在提升代码质量、可读性和健壮性。

命名约定

良好的命名是代码可读性的基石，应遵循“见名知意”的原则。

• 通用性与简洁性：使用通用的，简介的命名，避免晦涩难懂的缩写和歧义。
• 合理统一缩写：缩写要合理统一的使用。
• 适用范围：工程名，类名，接口名，方法名，变量名，对外暴露的接口命名均应遵循此规范。

代码编写原则

代码构建时应遵从以下核心原则，确保代码质量和可维护性：

• 设计直觉化：设计应符合直觉。
• 消除重复代码（DRY原则）：减少重复代码，通过下线或合并相同功能的服务等方式，减少冗余代码。
• 追求可读性：
• • 追求可读性，可读性不应依赖注释和文档。
• • 注释和文档并不是越多越好。
• 防御性编码：考虑到错误的入参和路径，提取规避错误。
• 配置化管理：配置化，避免硬编程。

注释规范

注释是对代码的补充说明，应精简有效。

• 不宜过多：注释不宜过多。好的代码本身就是很清晰。
• 高级技巧解释：用了高级技巧的地方尽量写注释。
• 参数意义明确：有些参数要注明意义。

异常处理规范

有效的异常处理是确保系统稳定性和用户体验的关键。

• 声明具体异常：如果声明异常，一定要声明具体的异常避免泛化的 Exception。
• 捕获具体异常：尽量捕获具体的异常，而不是捕获泛化的 Exception。
• 异常传递与封装：
• • 避免空 catch 块吞噬异常，至少需要记录日志。
• • Catch 之后封装成新异常抛出时，不用记录日志，抛出的异常会有上一层来处理和记录日志。
• • 基于 mybatis 的 Dao 层不需要抛出异常，Service 要捕获异常 dao 异常，并抛出可读的业务异常。
• 用户友好性：
• • 不要将异常直接显示在页面 or 客户端。
• • 需要将异常堆栈转化为可读的描述信息，可以附加错误码供技术人员参考。

日志管理规范

高质量的日志是问题定位和系统追踪的重要依据。
• 日志框架选择：当下最好的规约：slf4+logback。使用门面模式的日志框架。
• Lombok支持：可以使用 Lombok 的日志注解。
• 记录内容精准：日志中只记录方便定位问题的信息，切忌直接输出整个对象的 toString。
• 占位符使用：推荐使用 slf4 占位符，提升可读性。
• 日志文件命名：日志文件命名规范：appName_logType_logName。
• 提高日志可读性：方便问题定位，链路追踪。

版本控制与协作规范（Git）

高效的版本控制是团队协作的生命线。

Git 分支策略

代码分支主要分为：master，feature，hotfix，test 四大类。
• master 分支：
o 作为项目主分支，禁止直接在 master 上做任何修改和开发。
o 只能从 test 分支合并通过测试的代码。
• feature 分支：
o 开发新功能时需要从 master 拉出新分支，定为 feature 分支。
o 命名规则 feature-日期-关键字。
• hotfix 分支：
o 进行 bug 修复时创建的分支。
o 如果线上服务出现 bug，这时需要从 master 拉出新分支进行 bug 修复。
o 命名规则 hotfix-日期-关键词。
• test 分支：
o 需要 QA 创建的提测分支。
o 当 feature 和 hotfix 分支开发完成后，请求 merge 到 test 分支。
o 通过 test 分支创建 tag。
o 并把 test 分支合并到 master。
o 命名规则 test-日期-关键字。

代码提交与审核

• 小粒度提交：保存较小的提交粒度，一次只提交一件事（一个小功能点或者一个 bugfix）。
• 清晰的提交信息：提交记录要明确，commit message 要清晰。
• 提交前自查：提交前 review 一下自己的代码，建议 findbugs、checkstyle 进行检查。
• Git Push 频率：Git push 无需过于频繁，积攒几次提交再推送。

标签（Tag）管理

• 目的：对特点的提交点（commit）进行标记。
• 应用场景：发布版本时打一个 tag 记录此次发布的版本号，以及设计内容的简要信息。

常见代码“坏味道”与优化建议

识别并消除代码中的“坏味道”是持续改进代码质量的关键。
• If 嵌套过多：这通常会导致逻辑复杂、难以理解。解决：提前 return 返回。
• 代码重复：重复的代码是维护的噩梦。解决：抽取公共方法。