代码编写规范

知识管理系统代码编写规范一、介绍本文档为《知识管理系统》代码编写规范，为保证代码风格的一致性和后期的可维护性，文档讲述的内容要求所有开发人员必须遵守。本规范主要参考了GoogleJavaStyle，包括了其他一些业界约定俗成的公约和普遍采用的标准。本规范并非最终标准，一些规定还需再做商讨。1.1术语说明本文档除非特殊说明，否则：1.类（class）统指普通类、枚举类、接口和注解类型。2.注释（comment）只用来指实现注释（implementationcomments）。我们不使用“文档注释”这样的说法，而会直接说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字符（例如∞），或者对应的Unicode码（例如\u221e）转义都是允许的。唯一需要考虑的是，何种方式更能使代码容易阅读和理解。注意：在使用Unicode码转义，或者甚至是有时直接使用Unicode字符的时候，添加一点说明注释将对别人读懂代码很有帮助。三、源码文件结构源码文件按照先后顺序，由以下几部分组成：1.license或者copyright声明信息。（如果需要声明）2.包（package）声明语句。3.import语句。4.类声明（每个源码文件只能有一个顶级类）。每个部分之间应该只有一行空行作为间隔。3.1license或者copyright的声明信息。如果需要声明license或copyright信息，应该在文件开始时声明。3.2包声明包声明的行没有行长度的限制。单行长度限制不适用于包声明。3.3import语句3.3.1不使用通配符import即，不要出现类似这样的import语句：importjava.util.*;3.3.2没有行长度限制import语句的行没有行长度的限制。单行长度限制不适用于import语句所在行。3.3.3顺序和空行import语句应该被分为几个组，每个组之间由单行的空行隔开。分组的顺序如下：1.所有的静态导入为归为一组。2.com.sinosoft（项目自带包）包的import归为一组。3.第三方包。每个顶级包归为一组。第三方包之间按ASCII码排序。例如：android,com,junit,org,sun4.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.8.3.1节中讲到数组初始化，所有的数组初始化都可以被认为是一个块状结构（非强制）。4.1大括号4.1.1大括号不可省略大括号一般用在if,else,for,do和while等语句。即使当它的实现为空或者只有一句话时，也需要使用。4.1.2非空语句块采用K&R风格对于非空语句块，大括号遵循Kernighan&Ritchie风格：左大括号前不换行。左大括号后换行。右大括号前换行。如果右大括号结束一个语句块或者函数体、构造函数体或者有命名的类体，则右大括号后换行，否则不要换行。例如，当右大括号后面接else或者逗号时，不应该换行。例子：1.returnnewMyClass(){2.@Overridepublicvoidmethod(){3.if(condition()){4.try{5.someting();6.}catch(ProblemExceptione){7.recover();8.}9.}10.}11.};一些例外的情况，将在4.8.1节讲枚举类型的时候讲到。4.1.3空语句块：可以用简洁版本一个空的语句块，大括号可以简洁地写成{}，不需要换行。如果它是一个多块语句的一部分(if/else或try/catch/finally)，即使大括号内没内容，右大括号也要换行。例子：1.voiddoNothing(){}4.2语句块的缩进：4空格每当一个新的语句块产生，缩进就增加两个空格。当这个语句块结束时，缩进恢复到上一层级的缩进格数。缩进要求对整个语句块中的代码和注释都适用。（例子可参考之前4.1.2节中的例子）。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换行术语说明：当一行代码按照其他规范都合法，只是为了避免超出行长度限制而换行时，称为长行断行。长行断行，没有一个适合所有场景的全面、确定的规范。但很多相同的情况，我们经常使用一些行之有效的断行方法。注意：将长行封装为函数，或者使用局部变量的方法，也可以解决一些超出行长度限制的情况。并非一定要断行。4.5.1在何处断行断行的主要原则是：选择在更高一级的语法逻辑的地方断行。其他一些原则如下：1.在一个逗号后面断开。2.在一个操作符前面断开（=号和foreach语句的冒号除外）。3.在调用函数或者构造函数需要断行时，与函数名相连的左括号要在一行。也就是在左括号之后断行。4.5.2断行的缩进：至少8个字符当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。当原行之后有多个延续行的情况，缩进可以大于8个字符。如果多个延续行之间由同样的语法元素断行，它们可以采用相同的缩进。4.6.3节介绍水平对齐中，解决了使用多个空格与之前行缩进对齐的问题。4.6空白4.6.1垂直空白以下情况需使用一个空行：1.类成员之间需要空行隔开：字段、构造函数、方法、内部类、静态初始化语句块（staticinitializers）、实例初始化语句块（instanceinitializers）。o例外：连续字段之间的空白行不是必需的。一般多个字段中间的空行，是为了对字段做逻辑上的分组。2.在函数体内，语句的逻辑分组间使用空行。3.类的第一个成员之前，或者最后一个成员结束之后，用空行间隔。（可选）4.本文档中其他部分介绍的需要空行的情况。（例如3.3节中的import语句）单空行时使用多行空行是允许的，但是不要求也不鼓励。4.6.2水平空白除了语法和规范的其他规则，词语分隔、注释和Javadoc外，水平的ASCII空格只在以下情况出现：1.所有保留的关键字与紧接它之后的位于同一行的左括号（(）之间需要用空格隔开。（例如if、for、catch）2.所有保留的关键字与在它之前的右大括号（}）之间需要空格隔开。（例如else、catch）3.在左大括号（{）之前都需要空格隔开。只有两种例外：o@SomeAnnotation({a,b})oString[][]x={{foo}};4.所有的二元运算符和三元运算符的两边，都需要空格隔开。一元操作符和操作数之间不应该加空格，比如：负号(“-”)，自增(“++”)和自减(“--”)。例：i++;5.逗号、冒号、分号和右括号之后。6.如果在一条语句后做注释，则双斜杠(//)两边都要空格。这里可以允许多个空格，但没有必要。7.变量声明时，变量类型和变量名之间需要用空格隔开：ListStringlist。8.初始化一个数组时，大括号之间可以用空格隔开，也可以不使用。（例如：int[]{5,6}和newint[]{5,6}都可以）注意：这一原则并不要求或禁止一行开始或者结束时的空格。只针对行内部字符之间的隔开。4.6.3水平对齐：不做强制要求术语说明：水平对齐，是指通过添加多个空格，使本行的某一符号与上一行的某一符号上下对齐。这种对齐是允许的，但是不会做强制要求。以下是没有水平对齐和水平对齐的例子:1.privateintx;//thisisfine2.privateColorcolor;//thistoo3.4.privateintx;//permitted,butfutureedits5.privateColorcolor;//mayleaveitunaligned注意：水平对齐能够增加代码的可读性，但是增加了未来维护代码的难度。考虑到维护时只需要改变一行代码，之前的对齐可以不需要改动。为了对齐，你更有可能改了一行代码，同时需要更改附近的好几行代码，而这几行代码的改动，可能又会引起一些为了保持对齐的代码改动。这种改动，在最坏的情况下可能会导致大量的无意义的工作，即使在最好的情况下，也会影响版本历史信息，减慢代码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,33.}1.newint[]{2.0,3.1,4.2,5.36.}1.newint[]{2.0,1,3.2,34.}1.newint[]2.{0,1,2,3}4.8.3.2不能使用C风格的方式声明数组方括号应该是变量类型的一部分，因此不应该和变量名放在一起。例如：应该是String[]args，而不是Stringargs[]。4.8.4switch语句术语说明：swi