代码编写规范.docx

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

2、 文档说明本文档中的代码并不一定符合所有规范。即使这些代码遵循本规范，但这不是唯一的代码方式。例子中可选的格式风格也不应该作为强制执行的规范。二、源码文件基础 文件名源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。 文件编码：UTF-8源码文件使用UTF-8编码。 特殊字符 空格字符除了换行符外，ASCII 水平空白字符（0x20）是源码文件中唯一支持的空格字符。这意味着：1.其他空白字符将被转义。2.Tab字符不被用作缩进控制。 特殊转义字符串任何需要转义字符串表示的字符（例如b,?t,?n,?f,?r,?,?和等），采用这种转义字符串的方式表示，而不采用对应字符的八进制数

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

4、能有一个顶级类）。每个部分之间应该只有一行空行作为间隔。 license 或者 copyright 的声明信息。如果需要声明 license 或 copyright 信息，应该在文件开始时声明。 包声明包声明的行没有行长度的限制。单行长度限制不适用于包声明。 import语句 不使用通配符import即，不要出现类似这样的import语句：import .*; 没有行长度限制import 语句的行没有行长度的限制。单行长度限制不适用于import 语句所在行。 顺序和空行import语句应该被分为几个组，每个组之间由单行的空行隔开。分组的顺序如下：1.所有的静态导入为归为一组。2.（项目自带包

5、）包的import归为一组。3.第三方包。每个顶级包归为一组。第三方包之间按ASCII码排序。例如：android,?com,?junit,org,?sun4.java?包归为一组。5.javax?包归为一组。同一组内的import语句之间不应用空行隔开。同一组中的import语句按ASCII码排序。 类声明 只声明一个顶级类每个源码文件中只能有一个顶级类。例外：，该文件中可没有package-info类。 类成员顺序类成员的顺序对代码的易读性有很大影响，但这也不存在唯一的通用法则。不同的类可能有不同的排序方式。重要的是，每个类都要按照一定的逻辑规律排序。维护者应该要能解释这种排序逻辑。比如，

6、 新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。 重载方法：不应该分开当一个类有多个构造函数，或者多个同名成员方法时，这些函数应该写在一起，不应该被其他成员分开。四、格式术语说明：块状结构（block-like construct）指类、成员函数和构造函数的实现部分（大括号中间部分）。注意，在后面的节中讲到数组初始化，所有的数组初始化都可以被认为是一个块状结构（非强制）。 大括号 大括号不可省略大括号一般用在if,?else,?for,?do和while等语句。即使当它的实现为空或者只有一句话时，也需要使用。 非空语句块采用K & R风格对于非空语句块，大

7、括号遵循Kernighan & Ritchie风格： 左大括号前不换行。 左大括号后换行。 右大括号前换行。 如果右大括号结束一个语句块或者函数体、构造函数体或者有命名的类体，则右大括号后换行，否则不要换行。例如，当右大括号后面接else或者逗号时，不应该换行。例子：1.return new MyClass() 2. Override public void method() 3. if (condition() 4. try 5. someting();6. catch (ProblemException e) 7. recover();8. 9. 10. 11.;一些例外的情况，将在节讲枚

8、举类型的时候讲到。 空语句块：可以用简洁版本一个空的语句块，大括号可以简洁地写成，不需要换行。如果它是一个多块语句的一部分(if/else或try/catch/finally) ，即使大括号内没内容，右大括号也要换行。例子：1.void doNothing() 语句块的缩进：4空格每当一个新的语句块产生，缩进就增加两个空格。当这个语句块结束时，缩进恢复到上一层级的缩进格数。缩进要求对整个语句块中的代码和注释都适用。（例子可参考之前节中的例子）。 一行最多只有一句代码每句代码的结束都需要换行。 行长度限制：80或100不同的项目可以选择采用80个字符或者100个字符作为限制。除了以下几个特殊情况

9、外，其他代码内容都需要遵守这个长度限制。这在节会有详细解释。例外：?1. 按照行长度限制，无法实现地方（例如：Javadoc 中超长的 URL 地址， 或者一个超长的 JSNI 方法的引用）；?2.?package和import语句不受长度限制。（见、节）；?3. 注释中的命令行指令行，将被直接复制到shell中执行的。 换行术语说明：当一行代码按照其他规范都合法，只是为了避免超出行长度限制而换行时，称为长行断行。长行断行，没有一个适合所有场景的全面、确定的规范。但很多相同的情况，我们经常使用一些行之有效的断行方法。注意：将长行封装为函数，或者使用局部变量的方法，也可以解决一些超出行长度限制的

10、情况。并非一定要断行。 在何处断行断行的主要原则是：选择在更高一级的语法逻辑的地方断行。其他一些原则如下：?1. 在一个逗号后面断开。2. 在一个操作符前面断开?（= 号和foreach语句的冒号除外）。3. 在调用函数或者构造函数需要断行时，与函数名相连的左括号要在一行。也就是在左括号之后断行。? 断行的缩进：至少8个字符当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。?当原行之后有多个延续行的情况，缩进可以大于8个字符。如果多个延续行之间由同样的语法元素断行，它们可以采用相同的缩进。节介绍水平对齐中，解决了使用多个空格与之前行缩进对齐的问题。 空

11、白 垂直空白以下情况需使用一个空行：1.类成员之间需要空行隔开：字段、构造函数、方法、内部类、静态初始化语句块（static initializers）、实例初始化语句块（instance initializers）。?o例外：连续字段之间的空白行不是必需的。一般多个字段中间的空行，是为了对字段做逻辑上的分组。2.在函数体内，语句的逻辑分组间使用空行。3.类的第一个成员之前，或者最后一个成员结束之后，用空行间隔。（可选）4.本文档中其他部分介绍的需要空行的情况。（例如节中的 import 语句）单空行时使用多行空行是允许的，但是不要求也不鼓励。 水平空白除了语法和规范的其他规则，词语分隔、注释

12、和 Javadoc 外，水平的ASCII 空格只在以下情况出现：1.所有保留的关键字与紧接它之后的位于同一行的左括号（(）之间需要用空格隔开。（例如?if、for、catch）2.所有保留的关键字与在它之前的右大括号（）之间需要空格隔开。（例如else、catch）3.在左大括号（）之前都需要空格隔开。只有两种例外：?oSomeAnnotation(a, b)oString x = foo;4.所有的二元运算符和三元运算符的两边，都需要空格隔开。一元操作符和操作数之间不应该加空格，比如：负号(“-”)，自增(“+”)和自减(“-”)。例：i+;5.逗号、冒号、分号和右括号之后。1.如果在一条语

13、句后做注释，则双斜杠. 例外：?如果注解只有一个，并且不带参数。则它可以和类或方法名放在同一行。例如：1.Override public int hashCode() . 注解应用到字段时，也是紧接Javadoc之后。不同的是，多个注解可以放在同一行。例如：1.Partial Mock DataLoader loader;对于参数或者局部变量使用注解的情况，没有特定的规范。 注释 语句块的注释风格注释的缩进与它所注释的代码缩进相同。可以采用/* . */进行注释，也可以用.进行注释。当使用?/* . */进行多行注释时，每一行都应该以 * 开始， 并且 * 应该上下对齐。?注意文字和注释符之间

14、有一个空格（水平空白）。例如：1./*2. * This is * even do this. */3. */提示：多行注释时，如果你希望集成开发环境能自动对齐注释，你应该使用?/* . */，.一般不会自动对齐。 修饰符多个类和字段的修饰符，按?Java Language Specification?中介绍的先后顺序排序。具体是：1.public protected private abstract static final transient volatile synchronized native strictfp 数字型的字面值long类型的字面值使用大写L为后缀，永远不要使用小写l（

15、避免和1混淆）。例如：00L五、命名 适用于所有命名标识符的通用规范标示符只应该使用ASCII字母、数字，字母大小写敏感。因此所有的标示符，都应该能匹配正则表达式w+?。?标示符不需要使用特殊的前缀或后缀，如name_， mName， s_name 和 kName，在Java编程风格中都不再使用。 不同类型的标示符规范 包名包名全部用小写字母，将各单词简单地连在一起（不使用下划线）。例如：，不要使用或。 类名类名都以UpperCamelCase风格编写。?类名一般使用名词或名词短语，例如：Character或ImmutableList。接口名称一般也使用名词或名词短语（如：List），有时也可

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

17、用下划线隔开。（CONSTANCE_CASE）。常量的定义：每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时， 考虑它是否真的感觉像是一个常量。例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。 只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。下面是常量和非常量的例子：1.;1.(); StaticMethod(); .2. */3.public int method(String p1) .或者为单行格式：1./* An especially short bit of Javadoc. */通

18、用格式在任何时候使用都是可以的。当 Javadoc 块只有一行时，可以使用单行格式来替代通用格式。 段落空白行：是指Javadoc中，上下两个段落之间只有上下对齐的 * 字符的行。每个段落的第一行在第一个字符之前，有一个标签，并且之后不要有任何空格。 Javadoc标记所有标准的Javadoc标记，应该按照如下的顺序添加：param、return、throws、deprecated。并且如果这四种Javadoc标记出现，描述都不能为空。?当从句无法在一行写完时，应该断行。延续行在第一行的字符的位置，缩进至少4个字符单位。 摘要片段每个类或者成员的Javadoc，都是由一个摘要片段开始的。这个片

19、段非常重要。因为它是类或者方法在使用时唯一能看到的文本说明。?主要摘要只是一个片段，应该是一个名词短语或者动词短语，而不应该是一个完整的句子。不应该以类似于：A code Foo is a.或This method returns.这样的开头，但是它应该像一个完整的句子一样使用标点符号。提示：一种常见的错误是把单行形式的Javadoc写成：/* return the customer ID */，这是不对的。应该改为：/* Returns the customer ID. */。 何处应该使用Javadoc至少Javadoc 应该应用于所有的public类、public和protect的字段和

20、方法。以下是一些例外： 例外：方法本身已经足够说明的情况当方法本身很显而易见时，不需要Javadoc。例如：getFoo。没有必要加上Javadoc说明“Returns the foo”。?单元测试中的方法基本都能通过方法名，显而易见地知道方法的作用。因此不需要增加Javadoc。重要：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCannicalName?，就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。 例外：重载方法重载方法有时不需要再写 Javadoc。 例外：可选的Javadoc对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为，那么这个注释应该写成Javadoc，这样更统一更友好。注：本规范的大部分内容可用Eclipse格式化工具自动完成，所以提交代码时使用一次代码格式化是不错的选择。代码整洁