代码编写规范

精品文档 知识管理系统代码编写规范 一、介绍 本文档为《知识管理系统》代码编写规范，为保证代码风格的一致性和后期的可 维护性，文档讲述的内容要求所有开发人员必须遵守。 本规范主要参考了 Google Java Style，包括了其他一些业界约定俗成的公约和 普遍采用的标准。本规范并非最终标准，一些规定还需再做商讨。 1.1 术语说明 本文档除非特殊说明，否则： 1. 2. 类（class）统指普通类、枚举类、接口和注解类型。 注释（comment）只用来指实现注释（implementation comments） 。我们不使用“文 档注释”这样的说法，而会直接说Javadoc。 其他“术语说明”，将在文档中需要说明的地方单独说明。 1.2 文档说明 本文档中的代码并不一定符合所有规范。即使这些代码遵循本规范，但这不是唯 一的代码方式。例子中可选的格式风格也不应该作为强制执行的规范。 . 精品文档 二、源码文件基础 2.1 文件名 源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。 2.2 文件编码：UTF-8 源码文件使用UTF8编码。 2.3 特殊字符 2.3.1 空格字符 除了换行符外，ASCIIASCII 水平空白字符（水平空白字符（0 x20 0 x20） ）是源码文件中唯一支持的空格字 符。这意味着： 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. 2. 3. 4. license 或者 copyright 声明信息。 （如果需要声明） 包（package）声明语句。 import 语句。 类声明（每个源码文件只能有一个顶级类） 。 每个部分之间应该只有一行空行作为间隔。 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. 3. 所有的静态导入为归为一组。 com.sinosoft（项目自带包）包的 import 归为一组。 第三方包。每个顶级包归为一组。第三方包之间按ASCII 码排序。例如： android, com, junit,org, sun 4. 5. java 包归为一组。 javax 包归为一组。 同一组内的 import 语句之间不应用空行隔开。同一组中的 import 语句按 ASCII 码排序。 3.4 类声明 3.4.1 只声明一个顶级类 每个源码文件中只能有一个顶级类。 例外：packageinfo.java，该文件中可没有packageinfo类。 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 } catch (ProblemException e) { . 精品文档 7. 8. 9. 10. 11. recover(); } } } }; 一些例外的情况，将在 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. 在一个