代码编写规范.docx

1、代码编写规范知识管理系统代码编写规范一、介绍本文档为知识管理系统代码编写规范，为保证代码风格的一致性和后期的可维护性，文档讲述的内容要求所有开发人员必须遵守。本规范主要参考了Google Java Style，包括了其他一些业界约定俗成的公约和普遍采用的标准。本规范并非最终标准，一些规定还需再做商讨。1.1 术语说明本文档除非特殊说明，否则：1. 类（class）统指普通类、枚举类、接口和注解类型。2. 注释（comment）只用来指实现注释（implementation comments）。我们不使用“文档注释”这样的说法，而会直接说Javadoc。其他“术语说明”，将在文档中需要说明的地方

2、单独说明。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,和等），采用这种转义

3、字符串的方式表示，而不采用对应字符的八进制数（例如012）或 Unicode 码（例如u000a）表示。2.3.3 非 ASCII 字符对于其余非ASCII字符，直接使用Unicode字符（例如），或者对应的Unicode码（例如u221e）转义都是允许的。唯一需要考虑的是，何种方式更能使代码容易阅读和理解。注意：在使用Unicode码转义，或者甚至是有时直接使用Unicode字符的时候，添加一点说明注释将对别人读懂代码很有帮助。三、源码文件结构源码文件按照先后顺序，由以下几部分组成：1. license 或者 copyright 声明信息。（如果需要声明）2. 包（package）声明语句。

4、3. import 语句。4. 类声明（每个源码文件只能有一个顶级类）。每个部分之间应该只有一行空行作为间隔。3.1 license 或者 copyright 的声明信息。如果需要声明 license 或 copyright 信息，应该在文件开始时声明。3.2 包声明包声明的行没有行长度的限制。单行长度限制不适用于包声明。3.3 import语句3.3.1 不使用通配符import即，不要出现类似这样的import语句：import java.util.*;3.3.2 没有行长度限制import 语句的行没有行长度的限制。单行长度限制不适用于import 语句所在行。3.3.3 顺序和空行im

5、port语句应该被分为几个组，每个组之间由单行的空行隔开。分组的顺序如下：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

6、类。3.4.2 类成员顺序类成员的顺序对代码的易读性有很大影响，但这也不存在唯一的通用法则。不同的类可能有不同的排序方式。重要的是，每个类都要按照一定的逻辑规律排序。维护者应该要能解释这种排序逻辑。比如， 新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。3.4.2.1 重载方法：不应该分开当一个类有多个构造函数，或者多个同名成员方法时，这些函数应该写在一起，不应该被其他成员分开。四、格式术语说明：块状结构（block-like construct）指类、成员函数和构造函数的实现部分（大括号中间部分）。注意，在后面的4.8.3.1节中讲到数组初始化，所有的数组

7、初始化都可以被认为是一个块状结构（非强制）。4.1 大括号4.1.1 大括号不可省略大括号一般用在if,else,for,do和while等语句。即使当它的实现为空或者只有一句话时，也需要使用。4.1.2 非空语句块采用K & R风格对于非空语句块，大括号遵循Kernighan & Ritchie风格： 左大括号前不换行。 左大括号后换行。 右大括号前换行。 如果右大括号结束一个语句块或者函数体、构造函数体或者有命名的类体，则右大括号后换行，否则不要换行。例如，当右大括号后面接else或者逗号时，不应该换行。例子：1. return new MyClass() 2. Override publ

8、ic void method() 3. if (condition() 4. try 5. someting();6. catch (ProblemException e) 7. recover();8. 9. 10. 11. ;一些例外的情况，将在4.8.1节讲枚举类型的时候讲到。4.1.3 空语句块：可以用简洁版本一个空的语句块，大括号可以简洁地写成，不需要换行。如果它是一个多块语句的一部分(if/else或try/catch/finally) ，即使大括号内没内容，右大括号也要换行。例子：1. void doNothing() 4.2 语句块的缩进：4空格每当一个新的语句块产生，缩进就增

9、加两个空格。当这个语句块结束时，缩进恢复到上一层级的缩进格数。缩进要求对整个语句块中的代码和注释都适用。（例子可参考之前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. 注释中的命令行指

10、令行，将被直接复制到shell中执行的。4.5 换行术语说明：当一行代码按照其他规范都合法，只是为了避免超出行长度限制而换行时，称为长行断行。长行断行，没有一个适合所有场景的全面、确定的规范。但很多相同的情况，我们经常使用一些行之有效的断行方法。注意：将长行封装为函数，或者使用局部变量的方法，也可以解决一些超出行长度限制的情况。并非一定要断行。4.5.1 在何处断行断行的主要原则是：选择在更高一级的语法逻辑的地方断行。其他一些原则如下：1. 在一个逗号后面断开。2. 在一个操作符前面断开（= 号和foreach语句的冒号除外）。3. 在调用函数或者构造函数需要断行时，与函数名相连的左括号要在一

11、行。也就是在左括号之后断行。4.5.2 断行的缩进：至少8个字符当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。当原行之后有多个延续行的情况，缩进可以大于8个字符。如果多个延续行之间由同样的语法元素断行，它们可以采用相同的缩进。4.6.3节介绍水平对齐中，解决了使用多个空格与之前行缩进对齐的问题。4.6 空白4.6.1 垂直空白以下情况需使用一个空行：1. 类成员之间需要空行隔开：字段、构造函数、方法、内部类、静态初始化语句块（static initializers）、实例初始化语句块（instance initializers）。o 例外：连续字段

12、之间的空白行不是必需的。一般多个字段中间的空行，是为了对字段做逻辑上的分组。2. 在函数体内，语句的逻辑分组间使用空行。3. 类的第一个成员之前，或者最后一个成员结束之后，用空行间隔。（可选）4. 本文档中其他部分介绍的需要空行的情况。（例如3.3节中的 import 语句）单空行时使用多行空行是允许的，但是不要求也不鼓励。4.6.2 水平空白除了语法和规范的其他规则，词语分隔、注释和 Javadoc 外，水平的ASCII 空格只在以下情况出现：1. 所有保留的关键字与紧接它之后的位于同一行的左括号（(）之间需要用空格隔开。（例如if、for、catch）2. 所有保留的关键字与在它之前的右大

13、括号（）之间需要空格隔开。（例如else、catch）3. 在左大括号（）之前都需要空格隔开。只有两种例外：o SomeAnnotation(a, b)o String x = foo;4. 所有的二元运算符和三元运算符的两边，都需要空格隔开。一元操作符和操作数之间不应该加空格，比如：负号(“-”)，自增(“+”)和自减(“-”)。例：i+;5. 逗号、冒号、分号和右括号之后。6. 如果在一条语句后做注释，则双斜杠(/)两边都要空格。这里可以允许多个空格，但没有必要。7. 变量声明时，变量类型和变量名之间需要用空格隔开：List list。8. 初始化一个数组时，大括号之间可以用空格隔开，也可

14、以不使用。（例如：int 5, 6和new int 5, 6 都可以）注意：这一原则并不要求或禁止一行开始或者结束时的空格。只针对行内部字符之间的隔开。4.6.3 水平对齐：不做强制要求术语说明：水平对齐，是指通过添加多个空格，使本行的某一符号与上一行的某一符号上下对齐。这种对齐是允许的，但是不会做强制要求。以下是没有水平对齐和水平对齐的例子:1. private int x; / this is fine2. private Color color; / this too3. 4. private int x; / permitted, but future edits5. private

15、Color color; / may leave it unaligned注意：水平对齐能够增加代码的可读性，但是增加了未来维护代码的难度。考虑到维护时只需要改变一行代码，之前的对齐可以不需要改动。为了对齐，你更有可能改了一行代码，同时需要更改附近的好几行代码，而这几行代码的改动，可能又会引起一些为了保持对齐的代码改动。这种改动，在最坏的情况下可能会导致大量的无意义的工作，即使在最好的情况下，也会影响版本历史信息，减慢代码review的速度，引起更多merge代码冲突的情况。4.7 分组括号：建议使用除非作者和代码审核者都认为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于阅读，否则

16、我们不应该去掉小括号。我们没有理由假设读者能记住整个Java运算符优先级表。4.8 特殊结构4.8.1 枚举类型枚举常量间用逗号隔开，换行可选。没有方法和文档的枚举类可写成数组初始化的格式：例子：1. private enum Suit CLUBS, HEARTS, SPADES, DIAMONDS 枚举类型也是一个类（class），因此类的其他格式要求，也适用于枚举类型。4.8.2 变量声明4.8.2.1 每次声明一个变量不要使用组合声明。例如：int a, b;4.8.2.2 当需要时才声明，尽快完成初始化局部变量不应该习惯性地放在语句块的开始处声明，而应该尽量离它第一次使用的地方最近的地

17、方声明，以减小它们的使用范围。局部变量应该在声明的时候就进行初始化。如果不能在声明时初始化，也应该尽快完成初始化。4.8.3 数组4.8.3.1 数组初始化：可写成块状结构所有数组的初始化，都可以采用和块代码相同的格式处理。例如以下格式都是允许的：1. new int 2. 0, 1, 2, 33. 1. new int 2. 0,3. 1,4. 2,5. 36. 1. new int 2. 0, 1,3. 2, 34. 1. new int2. 0, 1, 2, 34.8.3.2 不能使用C风格的方式声明数组方括号应该是变量类型的一部分，因此不应该和变量名放在一起。例如：应该是String

18、args，而不是String args。4.8.4 switch语句术语说明：switch语句是指在switch大括号中，包含的一组或多组语句块。每组语句块都由一个或多个switch标签（case FOO:或者default:）打头。4.8.4.1 缩进和其他语句块一样，switch大括号之后缩进4个字符。每个switch标签之后，新起一行，再缩进4个字符，后面跟着一条或多条语句。在标签结束后，恢复到之前的缩进，类似大括号结束。4.8.4.2 fall-through注释在switch语句中，每个标签对应的代码执行完后，要么通过break、continue、return或抛出异常来终止，要么通

19、过注释说明代码将继续执行下一个标签的代码。任何能表达这个意思的注释都可以（典型的是使用/ fall through）。这个注释在最后一个标签之后不需要注释。例如：1. switch (input) 2. case 1:3. case 2:4. prepareOneOrTwo();5. / fall through6. case 3:7. handleOneTwoOrThree();8. break;9. default:10. handleLargeNumber(input);11. 4.8.4.3 default标签需要显式声明每个switch语句中，都需要显式声明default标签，即使它

20、没有任何代码。4.8.5 注解（Annotations）注解应用到类、函数或者构造函数时，应紧接Javadoc之后。注解独占一行。这里换行不属于长行换行(第4.5节，长行换行)，因此缩进级别不变。例如：1. Override2. Nullable3. public String getNameIfPresent() . 例外：如果注解只有一个，并且不带参数。则它可以和类或方法名放在同一行。例如：1. Override public int hashCode() . 注解应用到字段时，也是紧接Javadoc之后。不同的是，多个注解可以放在同一行。例如：1. Partial Mock DataLo

21、ader loader;对于参数或者局部变量使用注解的情况，没有特定的规范。4.8.6 注释4.8.6.1 语句块的注释风格注释的缩进与它所注释的代码缩进相同。可以采用/* . */进行注释，也可以用/ .进行注释。当使用/* . */进行多行注释时，每一行都应该以 * 开始， 并且 * 应该上下对齐。注意文字和注释符之间有一个空格（4.6.2水平空白）。例如：1. /*2. * This is / And so /* Or you can3. * okay. / is this. * even do this. */4. */提示：多行注释时，如果你希望集成开发环境能自动对齐注释，你应该使用

22、/* . */，/ .一般不会自动对齐。4.8.7 修饰符多个类和字段的修饰符，按Java Language Specification中介绍的先后顺序排序。具体是：1. public protected private abstract static final transient volatile synchronized native strictfp4.8.8 数字型的字面值long类型的字面值使用大写L为后缀，永远不要使用小写l（避免和1混淆）。例如：3000000000L五、命名5.1 适用于所有命名标识符的通用规范标示符只应该使用ASCII字母、数字，字母大小写敏感。因此所有的标

23、示符，都应该能匹配正则表达式w+。标示符不需要使用特殊的前缀或后缀，如name_， mName， s_name 和 kName，在Java编程风格中都不再使用。5.2 不同类型的标示符规范5.2.1 包名包名全部用小写字母，将各单词简单地连在一起（不使用下划线）。例如：com.example.deepspace，不要使用com.example.deepSpace或com.example.deep_space。5.2.2 类名类名都以UpperCamelCase风格编写。类名一般使用名词或名词短语，例如：Character或ImmutableList。接口名称一般也使用名词或名词短语（如：Lis

24、t），有时也可以使用形容词或形容词短语（如：Readable）。还没有特定的规则或行之有效的约定来命名注解类型。测试类的命名，应该以它所测试的类的名字为开头，并在最后加上Test结尾。例如：HashTest、HashIntegrationTest。5.2.3 方法名方法名都以lowerCamelCase风格编写。方法命名一般使用动词或者动词短语，例如：sendMessage或stop。在 JUnit 的测试方法中，可以使用下划线，用来区分逻辑组件的名字，经常使用如下的结构：test_。例如：testPop_emptyStack。并不存在唯一正确的方式来命名测试方法。5.2.4 常量名常量命名，

25、全部使用大写字符，词与词之间用下划线隔开。（CONSTANCE_CASE）。常量的定义：每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时， 考虑它是否真的感觉像是一个常量。例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。 只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。下面是常量和非常量的例子：1. / Constants2. static final int NUMBER = 5;3. static final ImmutableList NAMES = ImmutableList.of(E

26、d, Ann);4. static final Joiner COMMA_JOINER = Joiner.on(,); / because Joiner is immutable5. static final SomeMutableType EMPTY_ARRAY = ;6. enum SomeEnum ENUM_CONSTANT 7. 8. / Not constants9. static String nonFinal = non-final;10. final String nonStatic = non-static;11. static final Set mutableCollec

27、tion = new HashSet();12. static final ImmutableSet mutableElements = ImmutableSet.of(mutable);13. static final Logger logger = Logger.getLogger(MyClass.getName();14. static final String nonEmptyArray = these, can, change;常量一般使用名词或者名词短语命名。5.2.5 非常量的字段名非常量字段名以lowerCamelCase风格编写。一般使用名词或名词短语，例如：computed

28、Values或index。5.2.6 参数名参数名以lowerCamelCase风格编写。参数应该避免用单个字符命名。5.2.7 局部变量名局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。但即使如此，也应该尽量避免采用单个字母进行命名的情况，除了在循环体内使用的临时变量。即使局部变量是final、不可改变的，它也不能被认为是常量，也不应该采用常量的命名方式去命名。5.2.8 类型名类型名有两种命名方式：1. 单独一个大写字母，有时后面再跟一个数字。（例如，E、T、X、T2）。2. 像一般的类命名一样（见5.2.2节），再在最后接一个大写字母

29、T。（例如，RequestT、FooBarT）。5.3 驼峰式命名法（CamelCase）驼峰式命名法分大驼峰式命名法(UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。有时一些短语改写成驼峰形式的时候可以有多种写法。例如一些缩写词汇，或者一些组合词：IPv6 或者 iOS 等。为了统一写法，给出如下几乎可以确定为一种的写法：1. 将字符全部转换为 ASCII 字符，并且移除任何单引号。例如，Mllers algorithm 被转换为 Muellers algorithm 。2. 将上一步转换的结果切分成单词。从空格处或其它标点符号处分割开。o 注意：一些已经是驼

30、峰式的词语，也应该在这个时候被拆分。（例如 AdWords 被拆分为 ad words）。但是例如iOS之类的词语，它其实不是一个驼峰式的词语，而是人们惯例使用的一个词语，因此不用做拆分。3. 经过上面两步后，先将所有的字母转换为小写，再把每个词语的第一个字母或除第一个单词之外的单词的第一个字母转换为大写。4. 最后，将所有词语连在一起，形成一个标示符。注意：词语原来的大小写规则，应该被完全忽略。以下是一些例子：Prose formCorrectIncorrectXML HTTP requestXmlHttpRequestXMLHTTPRequestnew customer IDnewCustomerIdnewCustomerIDinner stopwatchinnerStopwatchinnerStopWatchsupports IPv6 on iOS?