一、编程规约

(八)、注释规约

1.【强制】类、类属性、类方法的注释必须使用Javadoc规范,使用/**内容*/格式,不得使用// xxx方式。

说明:在IDE编辑窗口中,Javadoc方式会提示相关注释,生成Javadoc可以正确输出相应注释;
在IDE中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。

2.【强制】所有的抽象方法(包括接口中的方法)必须要用Javadoc注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。

说明:对子类的实现要求,或者调用注意事项,请一并说明。

3.【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。

说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。

4.【推荐】无用的代码,应删除,而非注释。

说明:代码仓库保存了历史代码。代码仓库已有代码备份功能,无需将备份代码注释。
过多的无用代码会影响阅读代码的质量与速度。

5.【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

  • 待办事宜(TODO)

    表示需要实现,但目前还未实现的功能。这实际上是一个Javadoc的标签,目前的Javadoc还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个Javadoc标签)。

  • 错误,不能工作(FIXME)

    在注释中用FIXME标记某代码是错误的,而且不能工作,需要及时纠正的情况。

二、异常日志

(一)、异常处理

1.【强制】不要捕获Java类库中定义的继承自RuntimeException的运行时异常类(MdpExeption及其子类除外)。 如:IndexOutOfBoundsException/NullPointerException,这类异常由程序员预检查来规避,保证程序健壮性。

正例:if(obj != null) {...}

反例:try { obj.method() } catch(NullPointerException e){...}

2.【强制】对大段代码进行try-catch,这是不负责任的表现。 catch时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。 对于非稳定代码的catch尽可能进行区分异常类型,再做对应的异常处理。

3.【强制】捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之,如果不想处理它,请将该异常抛给它的调用者。 最外层的业务使用者,必须处理异常,将其转化为用户可以理解的内容。 在 TSP 中 最外层的已有异常处理类SimpleMappingExceptionResolver,编写业务类时可以只抛异常。 但若是ajax请求,在处理error(请求失败)时,需调用Mdp.handleException显示错误信息

4.【强制】try块放到了事务代码中,catch异常后,如果需要回滚事务,一定要注意手动回滚事务。

5.【强制】不能在finally块中使用returnfinally块中的return返回后方法结束执行,不会再执行try块中的return语句。

6.【强制】finally块必须对资源对象、流对象进行关闭,有异常也要做try-catch。

(二)、日志规约

1.【强制】异常信息应该包括两类信息:案发现场信息和异常堆栈信息。如果不处理,那么往上抛。

正例:logger.error(各类参数或者对象toString, e);

反例:logger.error(e.getMessage());

三、单元测试

1.【强制】好的单元测试必须遵守AIR原则。

说明:单元测试在线上运行时,感觉像空气(AIR)一样并不存在,但在测试质量的保障上,却是非常关键的。
好的单元测试宏观上来说,具有自动化、独立性、可重复执行的特点。
  • A:Automatic(自动化)
  • I:Independent(独立性)
  • R:Repeatable(可重复)

2.【强制】单元测试应该是全自动执行的,并且非交互式的。 测试用例通常是被定期执行的,执行过程必须完全自动化才有意义。 输出结果需要人工检查的测试不是一个好的单元测试。 单元测试中不准使用System.out来进行人肉验证,必须使用assert来验证。

3.【强制】保持单元测试的独立性。 为了保证单元测试稳定可靠且便于维护,单元测试用例之间决不能互相调用,也不能依赖执行的先后次序。

反例:method2需要依赖method1的执行,将执行结果作为method2的输入。

4.【强制】单元测试是可以重复执行的,不能受到外界环境的影响。

说明:单元测试通常会被放到持续集成中,每次有代码check in时单元测试都会被执行。
如果单测对外部环境(网络、服务、中间件等)有依赖,容易导致持续集成机制的不可用。

正例:为了不受外界环境影响,要求设计代码时就把SUT的依赖改成注入,在测试时用spring这样的DI框架注入一个本地(内存)实现或者Mock实现。

6.【强制】核心业务、核心应用、核心模块的增量代码确保单元测试通过。

说明:新增代码及时补充单元测试,如果新增代码影响了原有单元测试,请及时修正。

8.【推荐】单元测试的基本目标:语句覆盖率达到70%;核心模块的语句覆盖率和分支覆盖率都要达到100%

说明:可重用度高的`Service`,都应该进行单元测试。

10.【推荐】对于数据库相关的查询,更新,删除等操作,不能假设数据库里的数据是存在的,或者直接操作数据库把数据插入进去,请使用程序插入或者导入数据的方式来准备数据。

反例:删除某一行数据的单元测试,在数据库中,先直接手动增加一行作为删除目标,但是这一行新增数据并不符合业务插入规则,导致测试结果异常。

11.【推荐】和数据库相关的单元测试,可以设定自动回滚机制,不给数据库造成脏数据。 或者对单元测试产生的数据有明确的前后缀标识。

正例:在RDC内部单元测试中,使用RDC_UNIT_TEST_的前缀标识数据。

正例:TSP系统中,继承MdpTransactionalContextTests的类已自带回滚机制。

12.【推荐】对于不可测的代码建议做必要的重构,使代码变得可测,避免为了达到测试要求而书写不规范测试代码。

14.【参考】为了更方便地进行单元测试,业务代码应避免以下情况:

  • 构造方法中做的事情过多。
  • 存在过多的全局变量和静态方法。
  • 存在过多的外部依赖。
  • 存在过多的条件语句。

    说明:多层条件语句建议使用卫语句、策略模式、状态模式等方式重构。

15.【参考】不要对单元测试存在如下误解:

  • 那是测试同学干的事情。本文是开发手册,凡是本文内容都是与开发同学强相关的。
  • 单元测试代码是多余的。汽车的整体功能与各单元部件的测试正常与否是强相关的。
  • 单元测试代码不需要维护。一年半载后,那么单元测试几乎处于废弃状态。
  • 单元测试与线上故障没有辩证关系。好的单元测试能够最大限度地规避线上故障。

零、其他

1.【强制】Controller类中,不需要进行额外的异常处理,所有异常处理交个spring框架统一处理。

2.【推荐】Controller类中,不应出现业务逻辑;业务逻辑应封装至Service接口中,以便于单元测试和复用。

3.【推荐】Controller类中的Action方法的参数尽量不要使用Json对象来传参,尽量使用基本类型或定义的类(如DTO等)。

4.【推荐】少用Map对象进行传参(包括:入参、出参)。

说明:使用`Map`做为参数或返回值时,调用方或使用该方法的同学无法知道需要传递/返回哪些数据并进行校验。除非在javadoc中进行说明。

5.【推荐】ServiceDAO层的接口方法,在实现时应该对传入的参数进行合法性检查。 说明:防御式编程–人类都是不安全、不值得信任的,所有的人,都会犯错误,而你写的代码,应该考虑到所有可能发生的错误,让你的程序不会因为他人的错误而发生错误。

参考