编程规约

最新推荐文章于 2024-04-11 22:03:59 发布

qq_37783261

最新推荐文章于 2024-04-11 22:03:59 发布

阅读量172

点赞数

分类专栏：代码规约文章标签：代码规约

本文链接：https://blog.csdn.net/qq_37783261/article/details/102858832

版权

代码规约专栏收录该内容

1 篇文章 0 订阅

订阅专栏

(一) 文件编码
源文件编码格式为UTF-8。
(二) 命名风格

【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。反例：_name / __name / $Object / name_ / name$ / Object$
【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。正例： baidu/ youku / hangzhou 等国际通用的名称，可视同英文。反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3
【强制】类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：DO / BO / DTO / VO / AO 正例：MarcoPolo / XmlService / TcpUdpDeal / TaPromotion 反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。正例： localValue / getHttpMessage() / inputUserId
【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
正例：MAX_STOCK_COUNT 反例：MAX_COUNT
【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
【强制】中括号是数组类型的一部分，数组定义如下：String[] args; 反例：使用 String args[]的方式来定义。
【强制】POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。反例：定义为基本数据类型 Boolean isDelete；的属性，它的方法也是 isDeleted()，RPC框架在反向解析的时候，“以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。
【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。正例：应用工具类包名为 cn.lz.项目名缩写.mongo.controller、类名为 MessageController（此规则参考 spring 的框架结构）
【强制】杜绝完全不规范的缩写，避免望文不知义。反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。
【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
正例：接口方法签名：void f();
接口基础常量表示：String COMPANY = “userCount”;
反例：接口方法定义：public abstract void f();
说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。
接口和实现类的命名有两套规则：
1）【强制】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，接口的前缀拼上I与实现类区别。正例：CacheService 实现 ICacheService 接口。
2）【推荐】如果是形容能力的接口名称，取对应的形容词做接口名（通常是–able 的形式）。正例：AbstractTranslator 实现 Translatable。
【参考】枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKOWN_REASON。
【参考】各层命名规约：
A) Service/DAO 层方法命名规约
1）获取单个对象的方法用 get 做前缀。
2）获取多个对象的方法用 list 做前缀。
3）获取统计值的方法用 count 做前缀。
4）插入的方法用 save/insert 做前缀。
5）删除的方法用 remove/delete 做前缀。
6）修改的方法用 update 做前缀。
B) 领域模型命名规约
1）传参：xxxFilter，xxx 即为数据表名。
2）返回数据：xxxBean，xxx 为对象名称。

(三) 常量定义

【强制】不允许未经定义的常量直接出现在代码中。反例：String key = “Id#lz_” + tradeId; cache.put(key, value);
【强制】long 或者 Long 初始赋值时，使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误解。说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2?
【推荐】如果变量值仅在一个范围内变化，且带有名称之外的延伸属性，定义为枚举类。下面正例中的数字就是延伸信息，表示星期几。正例：public Enum { MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5), SATURDAY(6), SUNDAY(7);}
(四) 代码格式
【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则： 1）左大括号前不换行。 2）左大括号后换行。 3）右大括号前换行。 4）右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。
Public void delete(){

}
If(){
}else{
}
2. 【强制】左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。详见第 5 条下方正例提示。反例：if (空格 a == b 空格)
3. 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。正例：下例中实参的"a",后边必须要有一个空格。 method(“a”, “b”, “c”);
(五) OOP 规约

【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
Guardian guardian=new Guardian();
反例:String x=guardian.status;
正例:String x1=Guardian.status;
【强制】所有的覆写方法，必须加@Override 注解。说明：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错;
【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。正例：“test”.equals(object); 反例：object.equals(“test”);
【强制】所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较
【强制】POJO 类必须写 toString 方法。使用 IDE 的中工具：source> generate toString 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。

(六) 集合处理

【强制】使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一样的数组，大小就是 list.size()。说明：使用 toArray 带参方法，入参分配的数组空间不够大时，toArray 方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为[ list.size() ]的数组元素将被置为 null，其它数组元素保持原值，因此最好将方法入参数组大小定义与集合元素个数一致。
正例：
List list = new ArrayList(2);
list.add(“guan”);
list.add(“bao”);
String[] array = new String[list.size()];
array = list.toArray(array);
反例：直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[]类，若强转其它类型数组将出现 ClassCastException 错误。
【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。
正例：
Iterator iterator = list.iterator();
while (iterator.hasNext()) {
String item = iterator.next();
if (删除元素的条件) {
iterator.remove();
}
}
反例：
List a = new ArrayList();
list.add(“1”);
list.add(“2”);
for (String item : list) {
if (“1”.equals(item)) {
list.remove(item);
}
}
(七) 控制语句
【强制】在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式：if (condition) statements;
【推荐】表达异常的分支时，少用 if-else 方式，这种方式可以改写成：
if (condition) {
…
return obj;
}
// 接着写 else 的业务逻辑代码;
说明：如果非得使用 if()…else if()…else…方式表达逻辑，【强制】避免后续代码维护困难，请勿超过 3 层。
正例：超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，
其中卫语句示例如下：
public void today() {
if (isBusy()) {
System.out.println(“change time.”);
return;
}
if (isFree()) {
System.out.println(“go to travel.”);
return;
}
System.out.println(“stay at home to learn Java Coding Guidelines.”);
return;
}
(八) 注释规约
【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用 // xxx 方式。说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。说明：对子类的实现要求，或者调用注意事项，请一并说明。
/**
- Method description : 查询列表
- Author： xxx
- Create Date： xxxx年xx月xx日 x午xx:xx:xx
- History: xxxx年xx月xx日 x午xx:xx:xx xxx Created.
- @param ParameterFilter
*/
【强制】所有的类都必须添加创建者和创建日期
通用代码规范
1.注释
所有类、js文件、方法上必须注明作者，参数列表注释明确，方法作用注释明确，关键性代码，复杂逻辑代码段必须注释明确
2.编码
a.类名首字母大写，驼峰规则，例如：UserInfo
b.方法名，属性名，驼峰规则，例如：userName，getUserByParams();
c.每个方法尽量少于200行，在合适的地方进行封装调用，例如一个service中的持久操作，需要同时插入多张表，每张表都需要一段逻辑来处理，那么按照表的先后依赖关系，封装成多个方法，进行调用。
d.代码发布后，不允许出现system.out.println的打印输出代码，如果需要使用log进行打印。
e.类名方法名尽量少用缩写，以达到一眼就能看明白方法含义，如果必须使用缩写，使用通用公共约定的缩写，比如dao，mgr等
f.类和方法内，禁止出现未被使用的参数或者属性
g.对象使用前必须必须确定已经被初始化或者已经做过非空赋值
h.从数据库中所查询的数据，必须做非空判断，以及空值处理
i.上下文所传递参数，在未知空值与否情况下必须预先做空值处理
j.作用域范围缩进，不同作用域必须有各自的缩进让代码清晰化，if()后的花括号不得省略
k.再未完成，或者有待将来继续完善的代码处必须增加TODO标识，并且换行写上此处需要增加逻辑的注释
l.Static修饰符慎用，他属于类属性，不属于对象属性，一个类下的所有对象会共用该static修饰的属性，并且加锁后，会导致类加锁
m.系统常量全部写在Constant类中
n.工具类中不得出现spring注入的bean，并且放在util包中，保证可以不依赖于框架层独立调用，如果只是一个模块内的特殊工具，在模块中简历util包，放入其中，其他公用的放在common工程的util中
o.某些特殊类，如果希望禁止其被人集成，必须在类名前加上final修饰符，防止其他开发人员意外继承
p.如果类中方法已经过期，但为了保证其他引用该方法的地方不出错，务必加上@Deprecated注解，以提示后来的开发人员该方法已经不做维护
q.Synchronized线程锁在使用时尽量保证锁住内容在属性，代码块或者方法级上，防止太多不必要的线程等待
r.上下文传递参数时，参数个数不要超过4个，参数过多使用map或者java类传递
s.所有不需要修改值的变量，请加上final
t.所采用架构，基本代码是根据数据库中的业务表自动生成，所以禁止修改生成的标准方法，如果实在需要修改，请确认不会影响其他关联业务后再行修改，并且自己新增的方法或者类，格式标准参照生成的代码，并且满足以上所有标准
u.import不要使用通配符：不要出现这样的import语句 import java.util.*;
v.重载：永不分离。当一个类有多个构造函数时，或多个方法/函数同名时，这些方法/函数应该按顺序出现在一起，中间不要放入其他方法/函数
w.一行一个语句
x.每次只声明一个变量：不要使用组合声明比如int a, b;
y.每个switch语句都包含一个default语句组，即使它什么代码也不包含，也要写出来。
z.Finalizers禁用：不要使用finalize
所有finalizable的对象的finalize的执行是不确定的，既不确定由哪个线程执行，也不确定执行的顺序, 而这会因此所有可用堆内存被耗尽。结果就是不同口味的java.lang.OutOfMemoryError异常。