规则：编辑器列宽应设置为100列
说明： 当一行代码的长度过长时，为了阅读方便，应该换行展示。但因为每个人的字体设置，屏幕大小有所不同，因此需要统一列宽为100列。
补充：
在Eclipse中我们可以设置自动排版的单行代码最大宽度。选择：【Window】→【Preferences】→【Java】→【Code Style】→【Formatter】，点击“new”新建一个“Profile”（若已经是自定义的profile则不需要新建）。选择选项卡【Line Wrapping】,修改下边的“Maximum line width”为100。
在Eclipse中我们可以在编辑界面设置一条参考线提醒我们代码宽度。选择：【Window】→【Preferences】→【General】→【Editors】→【Text Editors】。将右侧的单选框“Show print margin”设置为选中状态，然后设置下边的“Print margin column”为100。

2.3 换行

规则：第二行相对第一行缩进4个空格，从第三行开始，不再缩进，而是与第二行保持同级。
规则：运算符、方法调用的点符号与下文一起换行。
规则：在多个参数超长时，逗号后换行。
示例：

//符合规范
StringBuffer sb = new StringBuffer();
//超过100个字符的时候，换行缩进4个空格，并且方法钱的点符号一起换行
sb.append("wan").append("fang")...
    .append("shu")...
    .append("ju")...
    .append("gu");
//在逗号后换行
method(arg1, arg2, arg3, ...argx, 
    argx1)

2.4 缩进

规则：程序块需要采用缩进风格编写，缩进为4个空格。
说明： 不同的编辑工具会导致Tab字符的宽度不统一，在编码时应注意其可能造成的问题。
补充：
在Eclipse中我们可以设置Tab的宽度和输入空格数。
选择：【Window】→【Preferences】→【General】→【Editors】→【Text Editors】。将右侧的“Display tab width”设置为4，将单选框“Insert spaces for tabs”设置为选中状态。
选择：【Window】→【Preferences】→【Java】→【Code Style】→【Formatter】，点击“new”新建一个“Profile”（若已经是自定义的profile则不需要新建）。选择选项卡【Indentation】,将左侧的下拉框“Tab policy”改为Spaces only。然后修改“Tab size”为4。

2.5 空行

规则：独立的程序块与变量声明之间加空行分割 示例：

//不符合规范
if(log.getLevel() < LogConfig.getRecordLevel()){
    return;
}
LogWriter writer;
int index;

//符合规范
if(log.getLevel() < LogConfig.getRecordLevel()){
    return;
}
  
LogWriter writer;
int index;

2.6 大括号

规则：使用大括号（即使是可选的）
说明： 大括号与if, else, for, do, while即使只有一条语句或是空，也应该把大括号写上。
示例：

//不符合规范的
if(writeToFile)
    writeFileThread.interrupt();

//符合规范的
if(writeToFile){
    writeFileThread.interrupt();
}

规则：对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格（紧凑风格）。
说明：

左大括号前不换行
左大括号后换行
右大括号前换行
如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。例如，如果右大括号后面是else或逗号，则不换行

示例：

//不符合规范
if(isOk)
{
    someThing();
}
else
{
    otherThing();
}

//符合规范
if(isOk){
    someThing();
}else{
    otherThing();
}

补充：
Kernighan和Ritchie风格指的是，Kernighan和Ritchie的《C Programming Language》一书中约定的“大括号放在同一行”规则。这种编码风格比较紧凑，也是Java官方和Google等诸多主流公司遵循的编码风格。

建议：空块可以简洁的写成{}，除非它是多块语句的一部分。
说明： 一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。例外：如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ，即使大括号内没内容，右大括号也要换行。
示例：

void doNothing() {}

2.7 小括号

规则：用小括号来限定计算优先级
说明： 没有理由假设代码的阅读者能够清晰的记住整个Java运算符优先级表。 ###2.8 空格 规则：函数参数在“，”后需要加空格。
规则：各种双目操作符，比如“=”，“<”等，前后都要加空格。
规则：if, while等关键字后面需要有空格。
补充： 基本上Eclipse的自动格式化功能，就能保证这些空格的正确使用。

2.9 TODO

规则：TODO用于任务标记，要避免出现无用的TODO标记
说明： 自动生成代码中如果有TODO标记，请根据需要编写注释或删除TODO标记，避免产生无用的TODO，影响他人跟踪任务。

2.10 import

规则：import不要使用通配符
说明： 不要出现类似这样的import语句：import java.util.*。使用通配符会造成歧义，及不可预期的冲突或bug。程序应保持清晰、易懂、无歧义。

规则：import不要引用不需要的包

2.11 变量

规则：每次只声明一个变量
说明： 不要使用组合声明（int a,b;），减少歧义性，增强可读性

规则：需要时才声明，并尽快进行初始化

规则：使用非C风格的数组声明
说明： 使用String[] args，而非String args[]

建议：谨慎的使用公共变量
说明： 公共变量是增大模块间耦合的原因之一，应减少没必要的公共变量以降低模块间的耦合度。

3 命名规范

规则：命名应尽可能做到见名知意，力求语义表达清晰完整。
规则：代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
规则：代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

3.1 package

规则：包名均采用小写
建议：包名一般为一个单词

规则：内部包名规则一般为com.部门名称/站点域名.产品名/项目名.模块名，通用包放在com.wanfangdata下
说明： 由于历史遗留原因，部分内部包名格式为：部门名称.产品名/项目名.模块名。原则上，新建的包不要用此命名规则，但暂时也不修改此规则的包名

3.2 Class

规则：类的命名应该都是名词
规则：类名第一个字母要为大写，其他每个单词的第一个字母为大写（UpperCamelCase）
规则：类名要用完整的单词，除非是被公认的单词缩写
规则：抽象类命名应以Abstract为开头
规则：异常类命名使用Exception结尾 规则：测试类命名以它要测试的类名称开始，以Test结尾

建议：如果使用了设计模式，建议在类(接口)命名中体现出具体的设计模式 建议：枚举类名以Enum后缀结束，美剧成员名称需要全部大写，单词间用下划线分隔。
示例：

public class BalanceLimitAccountHandler;
public interface SqlSessionFactory;
public class LoginProxy;

3.3 Interface

规则：接口名的命名应该是名词或形容词
规则：接口名应以大写的I开头，其他单词第一个字母都要大写（UpperCamelCase）
规则：接口名要用完整的单词，除非是被公认的单词缩写
建议：接口类中的方法和属性不要加任何修饰符好（public也不要加）。

3.4 方法命名

规则：方法名应以动词或惯用短语描述
规则：方法名第一个字母都要小写，其他每个单词第一个字母都要大写（lowerCamelCase）

建议：方法名中不要加入对象名字，可能会带来误解。
说明： 因为对象本身已经包含在调用语句中了

3.5 变量

规则：应避免用单个字符命名变量
规则：代码中严禁使用拼音与英文混合的方式，优先使用英文而非拼音

规则：参数名第一个字母使用小写，其他每个单词第一个字母大写（lowerCamelCase）

规则：常量名应该为名词或名词短语
规则：常量名每一个字母都应为大写，单词之间用“_”分开。

规则：不允许出现任何魔法值（未经定义的常量）直接出现在代码中。
建议：不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。

规则：long或者Long初始赋值时，必须使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。

规则：局部变量名第一个字母使用小写，其他每个单词第一个字母大写（lowerCamelCase）。
规则：局部变量名可以更宽松的使用缩写，但除了临时变量和循环变量应避免单字符命名。

规则：POJO类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。（参考阿里java规范）
说明：
定义为基本数据类型Boolean isSuccess；的属性，它的方法也是isSuccess()，RPC框架在反向解析的时候，“以为”对应的属性名称是success，导致属性获取不到，进而抛出异常。

4 注释规范

4.1 文档注释

规则：一般情况下，源程序有效注释量必须在30%以上。
规则：接口、Action方法、工具类的public方法等凡是提供给外界调用的方法都必须添加文档注释。
规则：文档注释用于描述Java的类、接口、构造函数、方法，一级成员变量（field）。

规则：类和接口的注释在 package 关键字之后，class 或者 interface 关键字之前。
规则：类和接口的注释内容：类的注释主要是一句话功能简述、功能详细描述。
说明： 可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。如果一个类存在Bug，请如实说明这些Bug

规则：对于接口需要标注

/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @author    [作者]
 * @see       [相关类/方法]
 * @deprecated
 */

示例：

/**
 * LogManager 类集中控制对日志读写的操作。
 * 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，
 * 读取或写入符合条件的日志纪录。
 * @author     张三，李四，王五
 * @see         LogIteraotor
 * @see         BasicLog
 */

规则：类属性、公有和保护方法注释：写在类属性、公有和保护方法上面
规则：成员变量使用文档注释，而不是单行注释或尾部注释
规则：成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方

规则：公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等
说明：

/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @param  [参数1]   [参数1说明]
 * @param  [参数2]   [参数2说明]
 * @return [返回值类型] [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
 * @see          [类、类#方法、类#成员]
 * @deprecated
 */

示例：

/**
 * 根据日志类型和时间读取日志。
 * 分配对应日志类型的LogReader， 指定类型、查询时间段、条件和反复器缓冲数，
 * 读取日志记录。查询条件为null或0表示无限制，反复器缓冲数为0读不到日志。
 * 查询时间为左包含原则，即 [startTime, endTime) 。
 * @param logTypeName  日志类型名（在配置文件中定义的）
 * @param startTime    查询日志的开始时间
 * @param endTime      查询日志的结束时间
 * @param logLevel     查询日志的级别
 * @param userName     查询该用户的日志
 * @param bufferNum    日志反复器缓冲记录数
 * @return LogIterator 结果集，日志反复器
 * @since  CommonLog1.0 
 */
public static LogIterator read(String logType, Date startTime, Date endTime, 
                               int logLevel, String userName, int bufferNum)

4.2 块注释

规则：块注释用来为文件、方法、数据结构和算法进行描述或是用来划分文件的模块
规则：块注释一般放在每个文件的开始或是每个模块、方法的前面，也可能放在方法之内
规则：在块注释前应该有一个空行，以便同其他代码进行分割

4.3 单行注释

规则：简短的注释可以只用一行来说明，并与后面的代码进行相同的缩进
规则：单行注释如果一行写不下，就应该考虑使用块注释
规则：在单行注释前应该有一个空行，以便痛其他代码进行分割

4.4 注意事项

规则：注释必须与代码同步更新
建议：应避免注释中提供代码中已清晰表达出来的重复信息
建议：当要写非文档注释的时候，应考虑下是否可以将代码写的更清晰易懂
说明： 过多的非文档注释，往往反映出代码的低质量
建议：TODO与FIXME注释格式建议包含（标记人，标记时间，[预计处理时间]）

5 编程技巧

5.1 类

规则：明确类的功能，精确（而非近似）地实现类的设计，一个类仅实现一组相近的功能
说明： 划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性
示例： 数据类不能包含数据处理的逻辑，通信类不能包含显示处理的逻辑

规则：所有的数据类必须重载toString() 方法，返回该类有意义的内容
说明： 如果父类中已经实现了较为合理的toString()方法，子类可以继承而不必重写

规则：只要重写equals，就必须重写hashCode。
规则：因为Set存储的是不重复的对象，依据hashCode和equals进行判断，所以Set存储的对象必须重写这两个方法。
规则：如果自定义对象做为Map的键，那么必须重写hashCode和equals。

建议：@Override能用则用
说明： 只要是合法的，就把@Override注解用上。
补充： 参考自谷歌编码规范

5.2 方法

规则：参数个数>4个时抽取参数类
建议：参数列表中请尽量不取用true、false类参数，避免因为调用者不明确导致的问题

建议：返回调用函数方应该知道的消息，慎用void
建议：返回空的集合时使用Collections.empty方法，不要直接返回null

规则：每个方法不得超过100行
建议：超过50行的代码建议考虑重构

规则：方法不得包含隐式功能
说明： 如：getIdsFromList(List modelList)仅应该执行从list获取id的操作，而不应该对list有修改

规则：避免使用不易理解的数字，用有意义的标识来替代
规则：涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的静态变量来代替

5.3 控制语句

规则：在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有
规则：在if/else/for/while/do语句中必须使用大括号，即使只有一行代码，避免使用下面的形式：if (condition) statements;

规则：尽量少用else
示例：

//不符合规范
if(condition)
{
    ...
    return obj;
}
//接着写else的业务逻辑代码

5.4 数据校验

建议：方法中需要进行参数校验的场景

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

建议：方法中不需要参数校验的场景

极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参数检查。
底层的方法调用频度都比较高，一般不校验。（参数错误不太可能到底层才会暴露问题）
被声明成private只会被自己代码所调用的方法。

Creators

引用自编码规范

原作者：梅葆瑞李辉张锐

18 KiB Raw Blame History Unescape Escape

JCNC编码规范

1 说明

1.1 范围

1.2 术语和定义

2 排版规则

2.1 编码

2.2 页宽

2.3 换行

2.4 缩进

2.5 空行

2.6 大括号

2.7 小括号

2.9 TODO

2.10 import

2.11 变量

3 命名规范

3.1 package

3.2 Class

3.3 Interface

3.4 方法命名

3.5 变量

4 注释规范

4.1 文档注释

4.2 块注释

4.3 单行注释

4.4 注意事项

5 编程技巧

5.1 类

5.2 方法

5.3 控制语句

5.4 数据校验

Creators

18 KiB

Raw Blame History