代码评审的18个军规

发布时间 2023-05-05 16:20:23作者: 郭慕荣

1. 添加必要的注释
其实,写代码的时候,没有必要写太多的注释,因为好的方法名、变量名,就是最好的注释。以下就是笔者总结的一些注释规范:

  • 所有的类都必须添加创建者和创建日期,以及简单的注释描述
  • 方法内部的复杂业务逻辑或者算法,需要添加清楚的注释
  • 一般情况下,注释描述类、方法、变量的作用
  • 任何需要提醒的警告或TODO,也要注释清楚
  • 如果是注释一行代码的,就用//;如果注释代码块或者接口方法的,有多行/* **/
  • 一块代码逻辑如果你站在一个陌生人的角度去看,第一遍看不懂的话,就需要添加注释了

2.日志打印规范
日志是快速定位问题的好帮手,是撕逼和甩锅的利器!打印好日志非常重要。如果代码评审的时候,这些日志规范没遵守,就需要修改:

  • 日志级别选择不对。常见的日志级别有error、warn、info、debug四种,不要反手就是info哈
  • 日志没打印出调用方法的入参和响应结果,尤其是跨系统调用的时候。
  • 业务日志没包含关键参数,如userId,bizSeq等等,不方便问题排查
  • 如果日志包含关键信息,比如手机号、身份证等,需要脱敏处理
  • 一些不符合预期的情况,如一些未知异常(数据库的数据异常等),又或者不符合业务预期的特殊场景,都需要打印相关的日志

3. 命名规范
Java代码的命名应该清晰、简洁和易于理解。我们代码评审的时候,要注意是否有命名不规范,不清晰的代码。下面是一些命名规范的建议:

  • 类和接口应该使用首字母大写的驼峰命名法
  • 方法和变量应该使用小写的驼峰命名法
  • 常量应该使用全大写字母和下划线
  • 开发者是不是选择易于理解的名称给变量、类和方法进行命名

4.参数校验
我们代码评审的时候,要注意参数是否都做了校验,如userId非空检查、金额范围检查、userName长度校验等等。一般我们在处理业务逻辑的时候,要遵循先检查、后处理的原则。
如果你的数据库字段userName设置为varchar(16),对方传了一个32位的字符串过来,你不校验参数,插入数据库直接异常了。
很多bug都是因为没做参数校验造成的,这一军规,是代码评审重点关注的哈:

5. 判空处理
获取对象的属性时,都要判空处理。要不然很多时候会出现空指针异常。

6. 异常处理规范
良好的异常处理可以确保代码的可靠性和可维护性。因此,异常处理也是代码评审的一项重要规范。以下是一些异常处理的建议:

  • 不要捕获通用的Exception异常,而应该尽可能捕获特定的异常
  • 在捕获异常时,应该记录异常信息以便于调试
  • 内部异常要确认最终的处理方式,避免未知异常当作失败处理。
  • 在finally块中释放资源,或者使用try-with-resource
  • 不要使用e.printStackTrace(),而是使用log打印。
  • catch了异常,要打印出具体的exception,否则无法更好定位问题
  • 捕获异常与抛出异常必须是完全匹配,或者捕获异常是抛异常的父类
  • 捕获到的异常,不能忽略它,要打印相对应的日志
  • 注意异常对你的代码层次结构的侵染(早发现早处理)
  • 自定义封装异常,不要丢弃原始异常的信息Throwable cause
  • 注意异常匹配的顺序,优先捕获具体的异常
  • 对外提供APi时,要提供对应的错误码
  • 系统内部应该抛出有业务含义的自定义异常,而不是直接抛出RuntimeException,或者直接抛出Exception\Throwable。

7. 模块化,可扩展性
代码评审的时候,关注一下,代码编写设计是否满足模块话,接口是否具有可扩展性
比如你的需求是酱紫:是用户添加或者修改员工时,需要刷脸。那你是反手提供一个员工管理的提交刷脸信息接口?还是先思考:提交刷脸是不是通用流程呢?比如转账或者一键贴现需要接入刷脸的话,你是否需要重新实现一个接口呢?还是当前按业务类型划分模块,复用这个接口就好,保留接口的可扩展性。
如果按模块划分的话,未来如果其他场景比如一键贴现接入刷脸的话,不用再搞一套新的接口,只需要新增枚举,然后复用刷脸通过流程接口,实现一键贴现刷脸的差异化即可。