带你读《2022技术人的百宝黑皮书》——开发规约的意义与细则（6）

带你读《2022技术人的百宝黑皮书》——开发规约的意义与细则（5）https://developer.aliyun.com/article/1339985?groupCode=taobaotech

注释规约

1. 注释的双斜线与注释内容之间有且仅有一个空格。正例：
   

  // 这是示例注释，请注意在双斜线之后有一个空格
  String commentString = new String();

2. 类、类属性、类方法的注释必须使用javadoc规范，使用/**内容*/格式，不得使用//xxx方式。说明：在IDE编辑   窗口中，javadoc方式会提示相关注释，生成javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
   
3. 所有的抽象方法（包括接口中的方法）必须要用javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。说明：对子类的实现要求，或者调用注意事项，请一并说明。
   
4. 所有的类都必须添加创建者信息和创建日期。说明：在设置模板时，注意IDEA的@author为${USER}，而eclipse的@author为${user}，大小写有区别，而日期的设置统一为yyyy/MM/dd的格式。
   

正例：

/**

@author wangchen（一律用花名） @date 2016/10/31 （yyyy/MM/dd）

*/

5. 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/ /注释，注意与代码对齐。
   
6. 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
   

7. 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
   
8. 在类中，删除未使用的任何字段和方法；在方法中，删除未使用的任何参数声明与内部变量。
   
9. 对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间， 也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
   

接口文档规约

1. 公共统一：统一返回的response格式，比如使用CommonResult，统一返回的错误码
   
2. 联调地址：测试环境地址，预发环境地址，生产环境地址；
   
3. 接口规约：接口名称，接口路径，请求方式，请求入参（名称，类型，是否空，字段描述），请求入参样例，返回参数（名称，类型，字段描述），返回参数样例；
   
4. 开发测试联调流程：日常环境 -> 预发环境 -> 生产环境，数据库同步环境：日常dev -> 预发 -> 生产
   

开发规约执行方法论

以上开发规约是基于《阿里巴巴 Java 开发手册》整理的特殊化需求，虽然《手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结， 经历了多次大规模一线实战的检验及不断完善，系统化地整理成册。当然，规范只能提供参考，我们还需要工具来帮忙我们实现了实时检测。

团队间项目的代码复查

在项目上线之前，在前端团队联调之后，在测试团队测试主体流程通过后，可以展开团队间相互code review，这个过程时间控制在半天左右。比如当前项目由主coder开发，可以由其他项目成员review，反过来同理。这种方法相对消耗时间成本，当然也有接下来这种方式。

带你读《2022技术人的百宝黑皮书》——开发规约的意义与细则（7）https://developer.aliyun.com/article/1339983?groupCode=taobaotech