编码规范

命名规范

1.代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束

2.代码和文件中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。 说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式 也要避免采用

    反例: DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3      正例: alibaba / taobao / youku / hangzhou 等国际通用的名称,可视同英文。 

3.类名使用 UpperCamelCase 风格,必须遵从大驼峰形式,但以下情形例外:(领域模型 的相关命名)DO / BO / DTO / VO等。

    正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion      反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion 

4.方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格,必须遵从小驼峰形式。

    正例: localValue / getHttpMessage() / inputUserId 

5.常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。

    正例: MAX_STOCK_COUNT     反例: MAX_COUNT 

6.抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类 命名以它要测试的类的名称开始,以 Test 结尾。

7.杜绝完全不规范的缩写,避免望文不知义。

    反例: AbstractClass“缩写”命名成 AbsClass;condition“缩写”命名成 condi,此类 随意缩写严重降低了代码的可阅读性。 

11.如果使用到了设计模式,建议在类名中体现出具体模式。

    说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计思想。      正例:public class OrderFactory;     public class LoginProxy; public class ResourceObserver; 

12.接口类中的方法和属性不要加任何修饰符号(public 也不要加),保持代码的简洁 性,并加上有效的注释。尽量不要在接口里定义变量,如果一定要定义变量,肯定是 与接口方法相关,并且是整个应用的基础常量。

    正例:接口方法签名:void f();     接口基础常量表示:String COMPANY = "alibaba";     反例:接口方法定义:public abstract void f(); 

13.接口和实现类的命名有两套规则:

    对于 Service 和 DAO 类,基于 SOA 的理念,暴露出来的服务一定是接口,内部的实现类用 Impl 的后缀与接口区别。     正例:CacheServiceImpl 实现 CacheService 接口     如果是形容能力的接口名称,取对应的形容词做接口名(通常是–able 的形式)。 正例:AbstractTranslator 实现 Translatable。 

14.枚举类名建议带上 Enum 后缀,枚举成员名称需要全大写,单词间用下划线隔开

    说明:枚举其实就是特殊的常量类,且构造方法被默认强制是私有     正例:枚举名字:DealStatusEnum,成员名称:SUCCESS / UNKOWN_REASON。 

15.各层命名规约:

    A) Service/DAO层方法命名规约     1) 获取单个对象的方法用get做前缀。     2) 获取多个对象的方法用list做前缀。     3) 获取统计值的方法用count做前缀。     4) 插入的方法用save(推荐)或insert做前缀。 5) 删除的方法用remove(推荐)或delete做前缀。 6) 修改的方法用update做前缀。     B) 领域模型命名规约     1) 数据对象:xxxDO,xxx即为数据表名。     2) 数据传输对象:xxxDTO,xxx为业务领域相关的名称。     3) 展示对象:xxxVO,xxx一般为网页名称。     4) POJO是DO/DTO/BO/VO的统称,禁止命名成xxxPOJO 

格式规约

1.大括号的使用约定。如果是大括号内为空,则简洁地写成{}即可,不需要换行;如果是非空代码块则:

    左大括号前不换行。      左大括号后换行。     右大括号前换行。      右大括号后还有else等代码则不换行;表示终止的右大括号后必须换行。 

2.左小括号和右边相邻字符之间不出现空格;同样,右小括号和左边相邻字符之间也 不出现空格。详见第 5 条下方正例 示。

3.if/for/while/switch/do 等保留字与小括号之间都必须加空格。

4.任何运算符左右必须加一个空格。

    说明:运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号、三目运算符等。 

5.单行字符数限制不超过 120 个,超出需要换行,换行时遵循如下原则:

    第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进,参考示例。     运算符与下文一起换行。     方法调用的点符号与下文一起换行     在多个参数超长,逗号后进行换行     在括号前不要换行,见反例。      正例: StringBuffer sb = new StringBuffer();     //超过 120 个字符的情况下,换行缩进 4 个空格,并且方法前的点符号一起换行      sb.append("zi").append("xin")...       .append("huang")...       .append("huang")...       .append("huang");      反例:     StringBuffer sb = new StringBuffer();     //超过 120 个字符的情况下,不要在括号前换行     sb.append("zi").append("xin")...append("huang");     //参数很多的方法调用可能超过 120 个字符,不要在逗号前换行 method(args1, args2, args3, ...     , argsX); 

7.方法参数在定义和传入时,多个参数逗号后边必须加空格

    正例:下例中实参的"a",后边必须要有一个空格。 method("a", "b", "c"); 

8.IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式, 不要使用 windows 格式。


控制语句

1.在一个 switch 块内,每个 case 要么通过 break/return 等来终止,要么注释说明程 序将继续执行到哪一个 case 为止;在一个 switch 块内,都必须包含一个 default 语句并且 放在最后,即使它什么代码也没有。

2.在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码,避免使用 单行的形式:if (condition) statements;

3.表达异常的分支时,少用 if-else 方式,这种方式可以改写成:

    if (condition) { ...     return obj;      }     // 接着写 else 的业务逻辑代码;     说明:如果非得使用 if()...else if()...else...方式表达逻辑,【强制】请勿超过 3 层,超过请使用状态设计模式。     正例:逻辑上超过 3 层的 if-else 代码可以使用卫语句,或者状态模式来实现。 

4.除常用方法(如 getXxx/isXxx)等外,不要在条件判断中执行其它复杂的语句,将复 杂逻辑判断的结果赋值给一个有意义的布尔变量名,以提高可读性

    说明:很多 if 语句内的逻辑相当复杂,阅读者需要分析条件表达式的最终结果,才能明确什么 样的条件执行什么样的语句,那么,如果阅读者分析逻辑表达式错误呢 ?     正例://伪代码如下     boolean existed = (file.open(fileName, "w") != null) && (...) || (...); if (existed) {     ... }      反例:     if ((file.open(fileName, "w") != null) && (...) || (...)) { ...      } 

5.循环体中的语句要考量性能,以下操作尽量移至循环体外处理,如定义对象、变量、获取数据库连接,进行不必要的 try-catch 操作

    (这个 try-catch 是否可以移至循环体外)。 

6.接口入参保护,这种场景常见的是用于做批量操作的接口。

7.下列情形,需要进行参数校验:

    调用频次低的方法。     执行时间开销很大的方法。此情形中,参数校验时间几乎可以忽略不计,但如果因为参数错误导致中间执行回退,或者错误,那得不偿失。     需要极高稳定性和可用性的方法。     对外 供的开放接口,不管是RPC/API/HTTP接口。 5) 敏感权限入口。 

8.下列情形,不需要进行参数校验:

    极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。     底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道,参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中,部署在同一台服务器中,所 以 DAO 的参数校验,可以省略     被声明成private只会被自己代码所调用的方法,如果能够确定调用方法的代码传入参 数已经做过检查或者肯定不会有问题,此时可以不校验参数。 

注释规约

1.所有的类都必须添加创建者和创建日期。

2.方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/* */注释,注意与代码对齐。

3.所有的枚举类型字段必须要有注释,说明每个数据项的用途。

4.与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持 英文原文即可。

    反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。 

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

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

6.合理处理注释掉的代码。尽量在目标代码上方详细说明,而不是简单的注释掉。如果 无用,则直接删除。

    说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没     有备注信息,难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。 

7.对于注释的要求:

    第一、能够准确反应设计思想和代码逻辑     第二、能够 述业务含 义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同 天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看 的,使其能够快速接替自己的工作。 

8.好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的,一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。

9.对于“明确停止使用的代码和配置”,如方法、变量、类、配置文件、动态配置属性,等要坚决从程序中清理出去,避免造成过多垃圾。

Tagged:

发表评论

电子邮件地址不会被公开。 必填项已用*标注