代码编写规范

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

一、介绍

本文档为《知识管理系统》代码编写规范，为保证代码风格的一致性和后期的可维护性，文档讲述的内容要求所有开发人员必须遵守。

本规范主要参考了Google Java Style，包括了其他一些业界约定俗成的公约和普遍采用的标准。本规范并非最终标准，一些规定还需再做商讨。

1.1 术语说明

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

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

2. 注释（comment）只用来指实现注释（implementation comments）。我们不使用“文

档注释”这样的说法，而会直接说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.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 顺序和空行

import语句应该被分为几个组，每个组之间由单行的空行隔开。分组的顺序如下：

1. 所有的静态导入为归为一组。

2. com.sinosoft（项目自带包）包的import归为一组。

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-like construct）指类、成员函数和构造函数的实现部分（大括号中间部分）。注意，在后面的4.8.3.1节中讲到数组初始化，所有的数组初始化都可以被认为是一个块状结构（非强制）。

4.1 大括号

4.1.1 大括号不可省略

大括号一般用在if, else, for, do和while等语句。即使当它的实现为空或者只有一句话时，也需要使用。

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

对于非空语句块，大括号遵循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.};

一些例外的情况，将在4.8.1节讲枚举类型的时候讲到。

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

一个空的语句块，大括号可以简洁地写成{}，不需要换行。如果它是一个多块语句的一部分(if/else或try/catch/finally) ，即使大括号内没内容，右大括号也要换行。

例子：

1.void doNothing(){}

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个字符

当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。