优化你的代码风格规范

知识管理系统代码编写规范

一、简介

本文档为《知识管理系统》代码编写规范，为保证代码风格日勺一致性和后期日勺

可维护性，文档讲述的内容规定所有开发人员必须遵守。

本规范重要参照了GoogleJavaStyle,包括了其他某些业界约定俗成的公约和

普遍采用的原则。本规范并非最终原则，某些规定还需再做商讨。

1.1术语阐明

本文档除非特殊阐明，否则：

1.类（class）统指一般类、枚举类、接口和注解类型。

2.注释（comment）只用来指实现注释（implementationcomments）o我们不使用"文档

注释”这样H勺说法，而会直接说Javadoc。

其他“术语阐明”，将在文档中需要阐明的地方单独阐明。

1.2文档阐明

本文档中的代码并不一定符合所有规范。虽然这些代码遵照本规范，但这不是

唯一的代码方式。例子中可选的格式风格也不应当作为强制执行的规范。

二、源码文献基础

2.1文献名

源文献以其最顶层的类名来命名，大小写敏感，文献扩展名为.java。

2.2文献编码:UTF-8

源码文献使用UTF-8编码。

2.3特殊字符

2.3.1空格字符

除了换行符外，ASCII水平空白字符（0x20）是源码文献中唯一支持的空格字

符。这意味着：

1.其他空白字符将被转义。

2.Tab字符不被用作缩进控制。

2.3.2特殊转义字符串

任何需要转义字符串表达的字符（例如\b,\t,\n,\f,\r,\“，\，和\\等），采用

这种转义字符串的方式表达，而不采用对应字符的八进制数（例如\012）或

Unicode码（例如\u000a）表达。

2.3.3非ASCII字符

对于其他非ASCII字符，直接使用Unicode字符（例如8）,或者对应的

Unicode码（例如\u22ie）转义都是容许的U唯一需要考虑的是，何种方式更

能使代码轻易阅读和理解。

注意：在使用Unicode码转义，或者甚至是有时直接使用Unicode字符的时

候，添加一点阐明注释将对他人读懂代码很有协助。

三、源码文献构造

源码文献按照先后次序，由如下几部分构成：

1.license或者copyright申明信息。（假如需要申明）

2.包（package）申明语句。

3.import语句。

4.类申明（每个源码文献只能有一种顶级类）。

每个部分之间应当只有一行空行作为间隔。

3.第三方包。每个顶级包归为一组。第三方包之间按ASCII码排序。例如：

android,com,junit,org,sun

4.java包归为一组。

5.javax包归为一组。

同一组内的import语句之间不应用空行隔开。同一组中的import语句按ASCII

码排序。

3.4类申明

3.4.1只申明一种顶级类

每个源码文献中只能有一种顶级类。

例外：package-info,java*该文献中可没有package-info类。

3.4.2类组员次序

类组员口勺次序对代码的易读性有很大影响，但这也不存在唯一的通使用方法

则。不一样口勺类也许有不一样的排序方式。

重要的是，每个类都要按照一定的逻辑规律排序。维护者应当要能解释这种排

序逻辑。例如，新的措施不能总是习惯性地添加到类日勺结尾，由于这样就是准

时间次序而非某种逻辑来排序的。

3.4.2.1重载措施：不应当分开

当一种类有多种构造函数，或者多种同名组员措施时，这些函数应当写在一

起，不应当被其他组员分开。

四、格式

术语阐明：块状构造（block-likeconstruct）指类、组员函数和构造函数的实现

部分（大括号中间部分）。注意，在背面的节中讲到数组初始化，所有的数组

初始化都可以被认为是一种块状构造（非强制）。

4.1大括号

4.1.1大括号不可省略

大括号一般用在if,else,for,do和while等语句。虽然当它的实现为空或者只

有一句话时，也需要使用。

4.1.2非空语句块采用K&R风格

对于非空语句块，大括号遵照Kernighan&Ritchie风格：

•左大括号前不换行。

•左大括号后换行。

•右大括号前换行。

•假如右大括号结束一种语句块或者函数体、构造函数体或者有命名的类体，则右大括

号后换行，否则不耍换行。例如，当右大括号背面接else或者逗号时，不应当换行。

例子:

1.returnnewMyClass(){

2.gOverridepublicvoidmethod(){

3.if(condition()){

4.

5.sometingO;

6.}catch(ProblemExceptione){

7.recover();

8.

9.)

10.}

11.)；

某些例外的状况，将在节讲枚举类型的时候讲到。

4.1.3空语句块：可以用简洁版本

一种空日勺语句块，大括号可以简洁地写成｛1不需要换行。假如它是一种多块

语句的一部分(if/else或try/catch/finally),虽然大括号内没内容，右大括

号也要换行。

例子:

1.voiddoNothlng()()

4.2语句块的缩进：4空格

每当一种新日勺语句块产生，缩进就增长两个空格。当这个语句块结束时，缩进

恢复到上一层级H勺缩进格数。缩进规定对整个语句块中的代码和注释都合用。

（例子可参照之前节中H勺例子）。

4.3一行最多只有一句代码

每句代码的结束都需要换行。

4.4行长度限制：80或100

不一样的项目可以选择采用80个字符或者100个字符作为限制。除了如下几

种特殊状况外，其他代码内容都需要遵守这个长度限制。这在4.5节会有详细

解释。

例外：

1.按照行长度限制，无法实现地方（例如：Javadoc中超长日勺URL地址，

或者一种超长的JSNI措施日勺引用）；

2.package和import语句不受长度限制。（见3.2、3.3节）;

3.注释中日勺命令行指令行，将被直接复制到shell中执行日勺。

4.5换行

术语阐明：当一行代码按照其他规范都合法，只是为了防止超过行长度限制而

换行时，称为长行断行。

长行断行，没有一种适合所有场景的全面、确定日勺规范。但诸多相似H勺状况，

我们常常使用某些行之有效H勺断行措施。

注意：将长行封装为函数，或者使用局部变量的措施，也可以处理某些超过行

长度限制的状况。并非一定要断行。

4.5.1在何处断行

断行的重要原则是：选择在更高一级的语法逻辑口勺地方断行。其他某些原则如

下：

1.在一种逗号背面断开。

2.在一种操作符前面断开（=号和foreach语句的冒号除外）。

3.在调用函数或者构造函数需要断行时，与函数名相连的左括号要在一行。也

就是在左括号之后断行。

4.5.2断行日勺缩进：至少8个字符

当断行之后，在第一行之后H勺行，我们叫做延续行。每一种延续行在第一行的

基础上至少缩进四个字符。

当原行之后有多种延续行的状况，缩进可以不小于8个字符。假如多种延续行

之间由同样H勺语法元素断行，它们可以采用相似H勺缩进。

节简介水平对齐中，处理了使用多种空格与之前吁缩进对齐日勺问题。

4.6空白

4.6.1垂直空白

如下状况需使用一种空行：

1.类组员之间需要空行隔开：字段、构造函数、措施、内部类、静态初始化语句块

（staticinitializers）＞实例初始化语句块（instanceinitializers）»

o例外：持续字段之间时空白行不是必需的。一般多种字段中间的空行，是为了对

字段做逻辑上日勺分组。

2.在函数体内，语句B勺逻辑分组间使用空行工

3.类日勺第一种组员之前，或者最终一种组员结束之后，用空行间隔。（可选）

4.本文档中其他部分简介的需要空行的状况。（例如3.3节中的Mporl语句）

单空行时使用多行空行是容许的，不过不规定也不鼓励。

4.6.2水平空白

除了语法和规范日勺其他规则，词语分隔、注释和Javadoc夕卜，水平的ASCII

空格只在如下状况出现：

1.所有保留的关键字与紧接它之后的位于同一行的I左括号（（）之间需要用空格隔开。

（例如if、for、catch）

2.所有保留的关键字与在它之前的右人括号（｝）之间需要空格隔开。（例如else、

catch）

3.在左大括号（｛）之前都需要空格隔开。只有两种例外：

ogSomeAnnotation（｛ajb｝）

oString[][]x=｛｛"foo"｝）;

4.所有的二元运算符和三元运算符的两边，都需要空格隔开。一元操作符和操作数之间

不应当加空格，例如:负号（“-”），自增（“++”）和自减（“一”）o例：i++；

5.逗号、冒号、分号和右括号之后。

6.假如在一条语句后做注释，则双斜杠（//）两边都要空格。这里可以容许多种空格，但没

有必要。

7.变量申明时，变量类型和变量名之间需要用空格隔开：List<String>list,

8.初始化一种数组时，大括号之间可以用空格隔开，乜可以不使用。（例如：int口｛5,

6｝和newint[]｛5,6｝都可以）

注意：这一原则并不规定或严禁一行开始或者结束时的空格。只针对行内部字

符之间口勺隔开。

4.6.3水平对齐：不做强制规定

术语阐明：水平对齐，是指通过添加多种空格，使本行的某一符号与上一行的

某一符号上下对齐。

这种对齐是容许的，不过不会做强制规定。

如下是没有水平对齐和水平对齐日勺例子:

1.privateintx;//thisisfine

2.privateColorcolor;//thistoo

3.

4.privateintx;//permitted,butfutureedits

5.privateColorcolor;//mayleaveitunaligned

注意：水平对齐可以增长代码的可读性，不过增长了未来维护代码庇I难度。考

虑到维护时只需要变化一行代码，之前的对齐可以不需要改动。为了对齐，你

更有也许改了一行代码，同步需要更改附近日勺好几行代码，而这几行代码的改

动，也许又会引起某些为了保持对齐的代码改动。这种改动，在最坏口勺状况下

也许会导致大量日勺无意义的工作，虽然在最佳的状况下，也会影响版本历史信

息，减慢代码review的速度，引起更多merge代码冲突的状况。

4.7分组括号：提议使用

除非作者和代码审核者都认为去掉小括号也不会使代码被误解，或是去掉小括

号能让代码更易于阅读，否则我们不应当去掉小括号。我们没有理由假设读者

能记住整个Java运算符优先级表。

4.8特殊构造

4.8.1枚举类型

枚举常量间用逗号隔开，换行可选。

没有措施和文档的枚举类可写成数组初始化的格式：

例子：

1.privateenumSuit{CLUBS,HEARTS,SPADES,DIAMONDS}

枚举类型也是一种类（class）,因此类的其他格式规定，也合用于枚举类型。

4.8.2变量申明

4.8.2.1每次申明一种变量

不要使用组合申明。例如：inta,b;

4.8,2.2当需要时才申明，尽快完毕初始化

局部变量不应当习惯性地放在语句块的开始处申明，而应当尽量离它第一次使

用的地方近来的地方申明，以减小它们的使用范围。

局部变量应当在申明的时候就进行初始化。假如不能在申明时初始化，也应当

尽快完毕初始化。

4.8.3数组

4.8.3.1数组初始化：可写成块状构造

所有数组的初始化，都可以采用和块代码相似的格式处理。例如如下格式都是

容许时：

1.newint[]{

2.0,1,2,3

3.}

1.newint[]{

2.0,

3・1,

4.2,

5.3

6.}

1.newint[]{

2.0,1,

3.2,3

4.)

1.newint[]

2.{0,1,2,3}

4.8.3.2不能使用C风格的方式申明数组

方括号应当是变量类型日勺一部分，因此不应当和变量名放在一起。例如：应当

是String口args,而不是Stringargs[]o

4.8.4switch语句

术语阐明：switch语句是指在switch大括号中，包括的一组或多组语句块。每

组语句块都由一种或多种switch标签(caseF00:或者default:)打头。

4.8.4.1缩进

和其他语句块同样，SW计Ch大括号之后缩进4个字符。

每个sw忙h标签之后，新起一行，再缩进4个字符，背面跟着一条或多条语

句。在标签结束后，恢复到之前日勺缩进，类似大书号结束。

4.8.4.2fall-through注释

在switch语句中，每个标签对应的代码执行完后，要么通过break、

continue,return或抛出异常来终止，要么通过注释阐明代码将继续执行下一

种标签日勺代码。任何能体现这个意思H勺注释都可以(经典的是使用〃fall

through)o这个注释在最终一种标签之后不需要注释。例如：

1.switch(input){

2.case1:

3.case2:

4.prepareOneOrTwo();

5.//fallthrough

6.case3:

7.handleOneTwoOrThree();

8.break;

9.default:

10.handleLargeNumber(input);

11.}

4.8.4.3default标签需要显式申明

每个sw怔h语句中，都需要显式申明default标签，虽然它没有任何代码。

4.8.5注解(Annotations)

注解应用到类、函数或者构造函数时，应紧接Javadoc之后。注解独占一行。

这里换行不属于长行换行(第4.5节，长行换行)，因此缩进级别不变。例如：

1.@Override

2.@Nullable

3.publicStringgetNamelfPresent(){...}

例外：

假如注解只有一种，并且不带参数。则它可以和类或措施名放在同一行。例

如：

1.gOverridepublicinthashCode(){…}

注解应用到字段时，也是紧接Javadoc之后。不一样的是，多种注解可以放在

同一行。例如：

1.0Partial@MockDataLoaderloader;

对于参数或者局部变量使用注解日勺状况，没有特定的规范。

4.8.6注释

4.861语句块的注释风格

注释的缩进与它所注释日勺代码缩进相似。可以采用/*...*/进行注释，也可以

用〃•・・进行注释。当使用/*...*/进行多行注释时，每一行都应当以*开

始，并且*应当上下对齐。注意文字和注释符之间有一种空格（水平空

白）。

例如：

1./*

2.*Thisis//Andso/*Oryoucan

3.*okay.//isthis.*evendothis.*/

4.*/

提醒：多行注释时，假如你但愿集成开发环境能自动对齐注释，你应当使

用/*...*/,//...一般不会自动对齐。

4.8.7修饰符

多种类和字段的I修饰符，按《JavaLanguageSpecification》中简介日勺先后次

序排序。详细是:

1.publicprotectedprivateabstractstaticfinaltransientvolatile

synchronizednativestrictfp

4.8.8数字型口勺字面值

long类型日勺字面值使用大写L为后缀，永远不要使用小写1（防止和1混

淆•）。例如：L

五、命名

5.1合用于所有命名标识符的通用规范

标示符只应当使用ASCII字母、数字，字母大小写敏感。因此所有的标示符,

都应当能匹配正则体现式\w+。

标示符不需要使用特殊日勺前缀或后缀，如name_,mName,s_name和

kName,在Java编程风格中都不再使用。

5.2不一样类型日勺标示符规范

5.2.1包名

包名所有用小写字母，将各单词简朴地连在一起（不使用下划线）。例如：，

不要使用或。

5.2.2类名

类名都以UpperCameCase风格编写。

类名一般使用名词或名词短语，例如：Character或ImmutableList。接口名称

一般也使用名词或名词短语（如：List）,有时也可以使用形容词或形容词短

语（till：Readable）o还没有特定的规则或行之有效的约定来命名注解类型。

测试类日勺命名，应当以它所测试日勺类日勺名字为开头，并在最终加上Test结尾。

例如：HashTest、HashlntegrationTesto

5.2.3措施名

措施名都以lowerCamelCase风格编写。

措施命名一般使用动词或者动词短语，例如：sendMessage或stop。

在JUnit日勺测试措施中，可以使用下划线，用来辨别逻辑组件日勺名字，常常使

用如下H勺构造：test<NethodllnderTest>_<state><例如：

testPop_emptyStacko并不存在唯一对的）H勺方式来命名测试措施。

5.2.4常量名

常量命名，所有使用大写字符，词与词之间用下划线隔开。

（CONSTANCECASE）。

常量的定义：每个常量都是一种静态final字段，但不是所有静态final字段都

是常量。在决定一种字段与否是一种常量时，考虑它与否真的感觉像是一种常

量。例如，假如任何一种该实例日勺观测状态是可变的，则它几乎肯定不会是一

种常量。只是永远不打算变化对象一般是不够的，它要真日勺一直不变才能将它

示为常量。

下面是常量和非常量的例子：

1.//Constants

2.staticfinalintNUMBER=5;

3.staticfinalImmutableList<String>NAMES=ImmutableList.of("Ed'"^"

Ann");

4.staticfinalJoinerCOMMA_3OINER=Joiner.on(','//because3oine

risimmutable

5.staticfinalSomeMutableType[]EMPTY_ARRAY={}；

6.enumSomeEnum{ENUM_CONSTANT}

7.

8.//Notconstants

9.staticStringnonFinal-"non-final";

10.finalStringnonStatic="non-static";

11.staticfinalSet<String>mutableCollection=newHashSet<String>();

12.staticfinalImmutableSet<SomeMutableType>mutableElements=Immuta

bleSet.of(mutable);

13.staticfinalLoggerlogger=Logger.getLogger(MyClass.getName());

14.staticfinalString[]nonEmptyArray={"these","can","change");

常量一般使用名词或者名词短语命名。

5.2.5非常量H勺字段名

非常量字段名以lowerCamelCase风格编写。

一般使用名词或名词短语，例如：computedValues或index。

5.2.6参数名

参数名以lowerCamelCase风格编写。

参数应当防止用单个字符命名。

5.2.7局部变量名

局部变量名以lowerCamelCase风格编写，比起其他类型的I名称，局部变量名

可以有更为宽松日勺缩写。

但虽然如此，也应当尽量防止采用单个字母进行命名口勺状况，除了在循环体内

使用的临时变量。

虽然局部变量是final、不可变化的，它也不能被认为是常量，也不应当采用常

量的I命名方式去命名。

5.2.8类型名

类型名有两种命名方式：

1.单独一种大写字母，有时背面再跟一种数字。（例如，E、T、X、T2）o

2.像•般的类命名同样（见节），再在最终接一种大写字母T。（例如，RequestTs

FooBarT）o

5.3驼峰式命名法（CamelCase）

驼峰式命名法分大驼峰式命名法（UpperCamelCase）和小驼峰式命名法

（lowerCamelCase）o有时某些短语改写成驼峰形式日勺时候可以有多种写法。例

如某些缩写词汇，或者某些组合词：IPv6或者QS等。

为了统一写法，给出如下几乎可以确定为一种的写法：

1.将字符所有转换为ASCII字符，并且移除任何单引号。例如，"Miiller'salgorithm"被

转换为"Muellersalgorithm"（,

2.将上一步转换小J成果切提成单词。从空格处或其他标点符号处分割开。

o注意：某些已经是鸵峰式的词语，也应当在这个时候被拆分。（例如AdWords被

拆分为adwords）,不过例如iOS之类口勺词语，它其实不是一种驼峰式的词语，

而是人们通例使用的一种词语，因此不用做拆分。

3.通过上面两步后，先将所有的字母转换为小写，再把每个词语口勺第一种字母或除第一

种单词之外的单词的第一种字母转换为大写。

4.最终，将所有词语连在•起，形成•种标示符。

注意：词语本来的大小写规则，应当被完全忽视。如下是某些例子:

ProseformCorrectIncorrect

"XMLrequest"XmlRequestXMLRequest

"newcustomerID"newCustomerldnewCustomerlD

"innerstopwatch"innerStopwatchinnerStopWatch

"supportsIPv6oniOS?"supportslpv60nlossupportsIPv60nI0S

"YouTubeimporter"YouTubelmporter

Youtubeimporter*

*号表达可以接受，不过不提议使用。

注意：有些词语在英文中，可以用-连接使用，也可以不使用-直接使用。

例如“nonempty”和“non-empty”都是可以日勺。因此，措施名字为

checkNonempty或者checkNonEmpty都是可以日勺。

六、编程实践

6.1©override能用则用

只要是符合语法日勺，就把©override用上。

6.2异常捕捉不应当被忽视

•般状况下，catch住妁异常不应当被忽视，而是都需要做合适的处理。例如

将错误日志打印出来，或者假如认为这种异常不会发生，则应当作为断言异常

重新抛出。

假如这个catch住的)异常确实不需要任何处理，也应当通过注释做出阐明。例

如：

1.try{

2.inti=Integer.parselnt(response);

3.returnhandleNumericResponse(i);

4.}catch(NumberFormatExceptionok)(

5.//it'snotnumberic;that'sfine,justcontinue

6.}

7.returnHandleTextResponse(response);

例外：在测试类里，有时会针对措施与否会抛出指定时异常，这样的I异常是可

以被忽视的I。不过这个异常一般需要命名为：expectedo例如：

1.try{

2.emptyStack.pop();

3.fail();

4.}catch(NoSuchElementExceptionexpected){

5.}

6.3静态组员的访问：应当通过类，而不是对象

当一种静态组员被访问时，应当通过类名去访问，而不应当使用这个类的详细

实例对象。例如：

1.FooaFoo=…；

2.Foo.aStaticMethod();//good

3.aFoo.aStaticMethod();//bad

4.somethingThatYieldsAFoo().aStaticMethod();//verybad

6.4不使用Finalizers措施

重载Object.finalize措施是非常非常罕见的I。

提醒：不应当使用这以措施。假如你认为你必须使用，请先仔细阅读并理解

《EffectiveJava》第七条“AvoidFinalizers”。然后不要使用它。

七、Javadoc

7.1格式规范

7.1.1通用格式

最基本日勺Javadoc日勺通用格式如下例:

1**

2.*MultiplelinesofJavadoctextarewrittenhere,

3.*wrappe