代码编写规范
知识管理系统代码编写规范
一、介绍
本文档为《知识管理系统》代码编写规范，为保证代码风格的一致性和后期的可维护性，文档讲述的内容要求所有开发人员必须遵守。
本规范主要参考了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.returnnew MyClass(){
2.@Override publicvoid 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个字符
当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。
当原行之后有多个延续行的情况，缩进可以大于8个字符。如果多个延续行之间由同样的语法元素断行，它们可以采用相同的缩进。
4.6.3节介绍水平对齐中，解决了使用多个空格与之前行缩进对齐的问题。4.6 空白
4.6.1 垂直空白
以下情况需使用一个空行：
1. 类成员之间需要空行隔开：字段、构造函数、方法、内部类、静态初始化语句块（static
initializers）、实例初始化语句块（instance initializers）。
o例外：连续字段之间的空白行不是必需的。一般多个字段中间的空行，是为了对字段做逻辑上的分组。
2. 在函数体内，语句的逻辑分组间使用空行。
3. 类的第一个成员之前，或者最后一个成员结束之后，用空行间隔。（可选）
4. 本文档中其他部分介绍的需要空行的情况。（例如3.3节中的import 语句）
单空行时使用多行空行是允许的，但是不要求也不鼓励。
4.6.2 水平空白
除了语法和规范的其他规则，词语分隔、注释和Javadoc外，水平的ASCII 空格只在以下情况出现：
1. 所有保留的关键字与紧接它之后的位于同一行的左括号（(）之间需要用空格隔开。（例
如if、for、catch）
2. 所有保留的关键字与在它之前的右大括号（}）之间需要空格隔开。（例如else、catch）
3. 在左大括号（{）之前都需要空格隔开。只有两种例外：
o@SomeAnnotation({a, b})
o String[][] x = {{"foo"}};
4.所有的二元运算符和三元运算符的两边，都需要空格隔开。一元操作符和操作数之间不
应该加空格，比如：负号(“-”)，自增(“++”)和自减(“--”)。例：i++;
5. 逗号、冒号、分号和右括号之后。
6. 如果在一条语句后做注释，则双斜杠(//)两边都要空格。这里可以允许多个空格，但没
有必要。
7. 变量声明时，变量类型和变量名之间需要用空格隔开：List
8. 初始化一个数组时，大括号之间可以用空格隔开，也可以不使用。（例如：int[] {5,
6}和new int[] { 5, 6 }都可以）
注意：这一原则并不要求或禁止一行开始或者结束时的空格。只针对行内部字符之间的隔开。
4.6.3 水平对齐：不做强制要求
术语说明：水平对齐，是指通过添加多个空格，使本行的某一符号与上一行的某一符号上下对齐。
这种对齐是允许的，但是不会做强制要求。
以下是没有水平对齐和水平对齐的例子:
1.privateint x;// this is fine
2.private Color color;// this too
3.
4.privateint x;// permitted, but future edits
5.private Color color;// may leave it unaligned
注意：水平对齐能够增加代码的可读性，但是增加了未来维护代码的难度。考虑到维护时只需要改变一行代码，之前的对齐可以不需要改动。为了对齐，你更有可能改了一行代码，同时需要更改附近的好几行代码，而这几行代码的改动，可能又会引起一些为了保持对齐的代码改动。这种改动，在最坏的情况下可能会导致大量的无意义的工作，即使在最好的情况下，也会影响版本历史信息，减慢代码review的速度，引起更多merge代码冲突的情况。
4.7 分组括号：建议使用
除非作者和代码审核者都认为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于阅读，否则我们不应该去掉小括号。我们没有理由假设读者能记住整个Java运算符优先级表。
4.8 特殊结构
4.8.1 枚举类型
枚举常量间用逗号隔开，换行可选。
没有方法和文档的枚举类可写成数组初始化的格式：
例子：
1.privateenum Suit{ CLUBS, HEARTS, SPADES, DIAMONDS }
枚举类型也是一个类（class），因此类的其他格式要求，也适用于枚举类型。
4.8.2 变量声明
4.8.2.1 每次声明一个变量
不要使用组合声明。例如：int a, b;
4.8.2.2 当需要时才声明，尽快完成初始化
局部变量不应该习惯性地放在语句块的开始处声明，而应该尽量离它第一次使用的地方最近的地方声明，以减小它们的使用范围。
局部变量应该在声明的时候就进行初始化。如果不能在声明时初始化，也应该尽快完成初始化。
4.8.3 数组
4.8.3.1 数组初始化：可写成块状结构
所有数组的初始化，都可以采用和块代码相同的格式处理。例如以下格式都是允许的：
1.newint[]{
2.0,1,2,3
3.}
1.newint[]{
2.0,
3.1,
4.2,
5.3
6.}
1.newint[]{
2.0,1,
3.2,3
4.}
1.newint[]
2.{0,1,2,3}
4.8.3.2 不能使用C风格的方式声明数组
方括号应该是变量类型的一部分，因此不应该和变量名放在一起。例如：应该是String[] 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或抛出异常来终止，要么通过注释说明代码将继续执行下一个标签的代码。任何能表达这个意思的注释都可以（典型的是使用// fall through）。这个注释在最后一个标签之后不需要注释。例如：
1.switch(input){
2.case1:
3.case2:
4. prepareOneOrTwo();
5.// fall through
6.case3:
7. handleOneTwoOrThree();
8.break;
9.default:
10. handleLargeNumber(input);
11.}
4.8.4.3 default标签需要显式声明
每个switch语句中，都需要显式声明default标签，即使它没有任何代码。4.8.5 注解（Annotations）
注解应用到类、函数或者构造函数时，应紧接Javadoc之后。注解独占一行。这里换行不属于长行换行(第4.5节，长行换行)，因此缩进级别不变。例如：
1.@Override
2.@Nullable
3.public String getNameIfPresent(){...}
例外：
如果注解只有一个，并且不带参数。则它可以和类或方法名放在同一行。例如：
1.@Override publicint hashCode(){...}
注解应用到字段时，也是紧接Javadoc之后。不同的是，多个注解可以放在同一行。例如：
1.@Partial@Mock DataLoader loader;
对于参数或者局部变量使用注解的情况，没有特定的规范。
4.8.6 注释
4.8.6.1 语句块的注释风格
注释的缩进与它所注释的代码缩进相同。可以采用/* ... */进行注释，也可以用// ...进行注释。当使用/* ... */进行多行注释时，每一行都应该以* 开始，
并且* 应该上下对齐。注意文字和注释符之间有一个空格（4.6.2水平空白）。例如：
1./*
2. * This is // And so /* Or you can
3. * okay. // is this. * even do this. */
4.*/
提示：多行注释时，如果你希望集成开发环境能自动对齐注释，你应该使用/* ... */，// ...一般不会自动对齐。
4.8.7 修饰符
多个类和字段的修饰符，按《Java Language Specification》中介绍的先后顺序排序。具体是：
1.publicprotectedprivateabstractstaticfinaltransientvolatilesynchroni
zednativestrictfp
4.8.8 数字型的字面值
long类型的字面值使用大写L为后缀，永远不要使用小写l（避免和1混淆）。例如：3000000000L
五、命名
5.1 适用于所有命名标识符的通用规范
标示符只应该使用ASCII字母、数字，字母大小写敏感。因此所有的标示符，都应该能匹配正则表达式\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。接口名称一般也使用名词或名词短语（如：List），有时也可以使用形容词或形容词短语（如：Readable）。还没有特定的规则或行之有效的约定来命名注解类型。
测试类的命名，应该以它所测试的类的名字为开头，并在最后加上Test结尾。例如：HashTest、HashIntegrationTest。
5.2.3 方法名
方法名都以lowerCamelCase风格编写。
方法命名一般使用动词或者动词短语，例如：sendMessage或stop。
在JUnit 的测试方法中，可以使用下划线，用来区分逻辑组件的名字，经常使用如下的结构：test
5.2.4 常量名
常量命名，全部使用大写字符，词与词之间用下划线隔开。（CONSTANCE_CASE）。
常量的定义：每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时，考虑它是否真的感觉像是一个常量。例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。
下面是常量和非常量的例子：
1.// Constants
2.staticfinalint NUMBER =5;
3.staticfinal ImmutableList
");
4.staticfinal Joiner COMMA_JOINER =Joiner.on(',');// because Joiner is
immutable
5.staticfinal SomeMutableType[] EMPTY_ARRAY ={};
6.enum SomeEnum{ ENUM_CONSTANT }
7.
8.// Not constants
9.static String nonFinal ="non-final";
10.f inal String nonStatic ="non-static";
11.s taticfinal Set
12.s taticfinal ImmutableSet
Set.of(mutable);
13.s taticfinal Logger logger =Logger.getLogger(MyClass.getName());
14.s taticfinal String[] nonEmptyArray ={"these","can","change"};
常量一般使用名词或者名词短语命名。
5.2.5 非常量的字段名
非常量字段名以lowerCamelCase风格编写。
一般使用名词或名词短语，例如：computedValues或index。
5.2.6 参数名
参数名以lowerCamelCase风格编写。
参数应该避免用单个字符命名。
5.2.7 局部变量名
局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。
但即使如此，也应该尽量避免采用单个字母进行命名的情况，除了在循环体内使用的临时变量。
即使局部变量是final、不可改变的，它也不能被认为是常量，也不应该采用常量的命名方式去命名。
5.2.8 类型名
类型名有两种命名方式：
1. 单独一个大写字母，有时后面再跟一个数字。（例如，E、T、X、T2）。
2. 像一般的类命名一样（见5.2.2节），再在最后接一个大写字母T。（例如，RequestT、
FooBarT）。
5.3 驼峰式命名法（CamelCase）
驼峰式命名法分大驼峰式命名法(UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。有时一些短语改写成驼峰形式的时候可以有多种写法。例如一些缩写词汇，或者一些组合词：IPv6 或者iOS 等。
为了统一写法，给出如下几乎可以确定为一种的写法：
1. 将字符全部转换为ASCII 字符，并且移除任何单引号。例如，"Müller's algorithm" 被
转换为"Muellers algorithm" 。
2. 将上一步转换的结果切分成单词。从空格处或其它标点符号处分割开。
o注意：一些已经是驼峰式的词语，也应该在这个时候被拆分。（例如AdWords 被拆分为ad words）。但是例如iOS之类的词语，它其实不是一个驼峰式的词语，而
是人们惯例使用的一个词语，因此不用做拆分。
3. 经过上面两步后，先将所有的字母转换为小写，再把每个词语的第一个字母或除第一个
单词之外的单词的第一个字母转换为大写。
4. 最后，将所有词语连在一起，形成一个标示符。
注意：词语原来的大小写规则，应该被完全忽略。以下是一些例子：
注意：有些词语在英文中，可以用- 连接使用，也可以不使用- 直接使用。例如“nonempty”和“non-empty”都是可以的。因此，方法名字为checkNonempty
或者checkNonEmpty都是可以的。
六、编程实践
6.1 @override能用则用
只要是符合语法的，就把@override用上。
6.2 异常捕获不应该被忽略
一般情况下，catch住的异常不应该被忽略，而是都需要做适当的处理。例如将错误日志打印出来，或者如果认为这种异常不会发生，则应该作为断言异常重新抛出。
如果这个catch住的异常确实不需要任何处理，也应该通过注释做出说明。例如：
1.try{
2.int i =Integer.parseInt(response);
3.return handleNumericResponse(i);
4.}catch(NumberFormatException ok){
5.// it's not numberic; that's fine, just continue
6.}
7.return HandleTextResponse(response);
例外：在测试类里，有时会针对方法是否会抛出指定的异常，这样的异常是可以被忽略的。但是这个异常通常需要命名为：expected。例如：
1.try{
2. emptyStack.pop();
3. fail();
4.}catch(NoSuchElementException expected){
5.}
6.3 静态成员的访问：应该通过类，而不是对象
当一个静态成员被访问时，应该通过类名去访问，而不应该使用这个类的具体实例对象。例如：
1.Foo aFoo =...;
2.Foo.aStaticMethod();// good
3.aFoo.aStaticMethod();// bad
4.somethingThatYieldsAFoo().aStaticMethod();// very bad
6.4 不使用Finalizers方法
重载Object.finalize方法是非常非常罕见的。
提示：不应该使用这以方法。如果你认为你必须使用，请先仔细阅读并理解《Effective Java》第七条“Avoid Finalizers”。然后不要使用它。
七、Javadoc
7.1 格式规范
7.1.1 通用格式
最基本的Javadoc的通用格式如下例：
1./**
2. * Multiple lines of Javadoc text are written here,
3. * wrapped normally...
4. */
5.publicint method(String p1){...}
或者为单行格式：
1./** An especially short bit of Javadoc. */
通用格式在任何时候使用都是可以的。当Javadoc块只有一行时，可以使用单行格式来替代通用格式。
7.1.2 段落
空白行：是指Javadoc中，上下两个段落之间只有上下对齐的* 字符的行。每个段落的第一行在第一个字符之前，有一个
标签，并且之后不要有任何空格。
7.1.3 Javadoc标记
所有标准的Javadoc标记，应该按照如下的顺序添加：@param、@return、@throws、@deprecated。并且如果这四种Javadoc标记出现，描述都不能为空。
当@从句无法在一行写完时，应该断行。延续行在第一行的@字符的位置，缩进至少4个字符单位。
7.2 摘要片段
每个类或者成员的Javadoc，都是由一个摘要片段开始的。这个片段非常重要。因为它是类或者方法在使用时唯一能看到的文本说明。
主要摘要只是一个片段，应该是一个名词短语或者动词短语，而不应该是一个完整的句子。不应该以类似于：A {@code Foo} is a...或This method returns...这样的开头，但是它应该像一个完整的句子一样使用标点符号。
提示：一种常见的错误是把单行形式的Javadoc写成：/** @return the customer ID */，这是不对的。应该改为：/** Returns the customer ID. */。
7.3 何处应该使用Javadoc
至少Javadoc应该应用于所有的public类、public和protect的字段和方法。以下是一些例外：
7.3.1 例外：方法本身已经足够说明的情况
当方法本身很显而易见时，不需要Javadoc。例如：getFoo。没有必要加上Javadoc 说明“Returns the foo”。
单元测试中的方法基本都能通过方法名，显而易见地知道方法的作用。因此不需要增加Javadoc。
重要：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCannicalName，就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。
7.3.2 例外：重载方法
重载方法有时不需要再写Javadoc。
7.3.3 例外：可选的Javadoc
对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为，那么这个注释应该写成Javadoc，这样更统一更友好。
注：本规范的大部分内容可用Eclipse格式化工具自动完成，所以提交代码时使用一次代码格式化是不错的选择。
代码整洁
代码编写规范
知识管理系统代码编写规范 一、介绍 本文档为《知识管理系统》代码编写规范，为保证代码风格的一致性和后期的可维护性，文档讲述的内容要求所有开发人员必须遵守。 本规范主要参考了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）转义都是允许的。唯一需要考虑的是，何种方式更能使代码容易阅读和理解。
程序代码注释编写规范
程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ COPYRIGHT (C), MicTiVo International. Co., Ltd. FileName: Author:
软件代码编写规范
? 软件销售代理合同范本软件代码编写规范 草稿 2005.2
? 软件销售代理合同范本 1 命名规则 https://www.sodocs.net/doc/9c6292154.html,命名规则 一致的命名模式是托管类库中可预知性与可发现性最重要的元素之一。对这些命名指南广泛的使用和理解将消除许多最常见的用户问题。本主题提供.NET Framework 类型的命名指南。对于每个类型，还应该注意关于大写样式、区分大小写和措词的一些通用规则。 1.1.1大写样式 描述用于在类库中命名标识符的Pascal 大小写、Camel 大小写和全部大写样式。 使用下面的三种大写标识符约定。 Pascal 大小写 将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal 大小写。例如： B ack C olor Camel 大小写 标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如： b ack C olor 大写 标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如： System.IO System.Web.UI 可能还必须大写标识符以维持与现有非托管符号方案的兼容性，在该方案中所有大写字母经常用于枚举和常数值。一般情况下，在使用它们的程序集之外这些字符应当是不可见的。 下表汇总了大写规则，并提供了不同类型的标识符的示例。 标识符大小写示例 类Pascal AppDomain 枚举类型Pascal ErrorLevel 枚举值Pascal FatalError 事件Pascal ValueChange 异常类Pascal WebException 注意总是以Exception后缀结尾。 只读的静态字段Pascal RedValue 接口Pascal IDisposable 注意总是以I 前缀开始。 方法Pascal ToString 命名空间Pascal System.Drawing 参数Camel typeName 属性Pascal BackColor
程序代码注释编写规范
百度文库- 让每个人平等地提升自我 1 程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* (C), MicTiVo International. Co., Ltd. 1.File : . History: Date: Author: Modification: 2. .. *************************************************/ 一、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ (C), MicTiVo International. Co., Ltd. FileName: Author: Version : Date: : / /*receive _process() */ 意:与溢出中断写初值不同}
华为JAVA编程规范
1 Java 编程规范 1.1 排版 1.1.1 规则 规则1程序块要采用缩进风格编写，缩进的空格数为4个，不允许使用TAB缩进。(1.42+) 说明：缩进使程序更易阅读，使用空格缩进可以适应不同操作系统与不同开发工具。 规则2分界符（如大括号…{?和…}?）应各独占一行，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序 或者static、,synchronized等语句块中都要采用如上的缩进方式。(1.42+) 示例: if (a>b) { doStart(); } 规则3较长的语句、表达式或参数（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐， 语句可读。(1.42+) 示例： if (logger.isDebugEnabled()) { logger.debug("Session destroyed,call-id" + event.getSession().getCallId()); } 规则4不允许把多个短语句写在一行中，即一行只写一条语句(1.42+) 说明：阅读代码更加清晰 示例：如下例子不符合规范。 Object o = new Object(); Object b = null; 规则5if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while,switch等语句的执行语句无论多少都要加括号{},case 的执行语句中如果定义变量必须加括号{}。 (1.42+) 说明：阅读代码更加清晰，减少错误产生 示例： if (a>b) { doStart(); }
SAP开发规范
目录 目录 (1) SAP开发规范 (3) 1说明 (3) 1.1内容说明 (3) 1.2规范目的 (3) 1.3使用说明 (3) 1.4使用对象 (3) 2一般规则 (3) 3代码管理 (4) 3.1程序标题 (4) 3.2子程序、模块标题 (5) 3.3编辑器设置 (5) 3.4代码格式 (7) 3.4.1使用规范化打印机 (7) 3.4.2查询SQL语句的写法 (7) 3.5变更记录管理 (7) 3.6代码注释 (8) 3.7子程序与函数模块 (9) 3.8其它注意事项 (9) 4数据库查询 (9) 4.1不要在L OOP循环中使用S ELECT语句 (9) 4.2取数的时候不能使用S ELECT......E NDSELECT语句循环操作 (9) 4.3尽量多使用内表 (9) 4.4S ELECT
5.2内表使用 (12) 5.2.1修改内表中的字段值 (12) 5.2.2把一个内表附加到另一个内表后面 (12) 5.2.3删除内表中重复行 (13) 5.2.4根据条件删除内表中的行 (13) 5.2.5内表是否为空的判断 (13) 5.2.6读取内表行 (13) 5.2.7通过LOOP AT it_tab ASSIGNING
程序代码编写规范
程序编写规范及约定 (仅供内部使用) 文档作者：_______________ 日期：___/___/___ 开发/测试经理：_______________ 日期：___/___/___ 项目经理：_______________ 日期：___/___/___ 请在这里输入公司名称 版权所有不得复制
目录 程序编写规范及约定 (3) 1编写目的 (3) 2代码编写风格 (3) 2.1单元风格 (3) 2.2语句风格 (3) 3命名规则 (3) 3.1命名约定 (3) 3.1.1标志符 (3) 3.1.2类class (3) 3.1.3枚举类型enum (4) 3.1.4委托delegate (4) 3.1.5常量const (4) 3.1.6接口interface (4) 3.1.7方法function (4) 3.1.8命名空间namespace (4) 3.1.9参数 (4) 3.1.10局部变量 (5) 3.1.11数据成员 (5) 3.1.12自定义异常类 (5) 3.1.13命名缩写 (5) 3.1.14数据库命名 (5) 3.2代码编写命名规范 (6) 3.3界面常用控件命名约定 (6) 3.4文件命名规范 (7) 3.4.1文档文件命名 (7) 3.4.2配置文件命名 (7) 3.4.3程序文件命名 (7)
程序编写规范及约定 1编写目的 为了使编写代码具有可读性、可理解性、可维护性，对程序编写人员代码实行统一风格，使得程序代码能够以名称反映含义、以形式反映结构。此文档可供程序代码编写人员及代码维护人员使用。 2代码编写风格 2.1单元风格 2.2语句风格 3命名规则 3.1命名约定 Pascal和Camel命名约定： 编程的命名方式主要有Pascal和Camel两种（Pascal：每个单词的首字母大写，例如ProductType；Camel：首个单词的首字母小写，其余单词的首字母大写，例如productType） 3.1.1标志符 规则：Pascal、Camel 实例与描述：例子说明 3.1.2类class 规则：Pascal 实例与描述：Application
Java代码编写规范(参考)
命名规范： 1.所有的标识都只能使用ASCII字母（A-Z或a-z）、数字（0-9）和 下划线”_”。 2.一个唯一包名的前缀总是用全部小写的字母。 3.类名是一个名词，采用大小写混合的方式，每个单词的首字母大 写。 4.接口的大小写规则与类名相似。 5.方法名是一个动词或是动词词组，采用大小写混合的方式，第一 个单词的首字母小写，其后单词的首字母大写。 6.变量名的第一个字母小写，任何中间单词的首字母大写，变量名 应简短且可以顾名思义，易于记忆。避免单个字符的变量名，除非是一次性的临时变量。 7.常量的声明应该全部大写，每个单词之间用”_”连接。 注释规范： 1.注释尽可能使用”//”,对于所有的Javadoc的注释使用/***/，而 临时对代码块进行注释应尽量使用/**/。 2.所有的源文件都应该在开头有一个注释，其中列出文件名、日期 和类的功能概述。每个方法必须添加文档注释（main除外）。 3.每个属性必须加注释。 4.代码中至少包含15%的注释。 5.注释使用中文。
缩进排版规范： 1.避免一行的长度超过60个字符。 2.使用Eclipse源代码的格式化功能完成代码的缩进排版。 文件名规范： 1.一个Java源文件只能储存一个Java类。 2.文件名与Java类相同。 3.一个类文件不超过200行。 声明规范： 1.一行声明一个变量。 2.不要将不同类型变量的声明放在同一行。 3.只在代块的开始处声明变量。 4.所有的变量必须在声明时初始化。 5.避免声明的局部变量覆盖上一级声明的变量。 6.方法与方法直接以空行分隔。 语句规范： 1.每行至少包含一条简单语句。 2.在return语句中，返回值不使用小括号”()”括起来。 3.If月总是用{和}括起来。 4.在for语句的初始化或者更新子句中，避免因使用3个以上变量， 而导致复杂度提高。 5.当switch的一个case顺着往下执行时（因为没有break），通常 应在break语句的位置添加注释。
软件开发代码规范C版
软件开发代码规范（C#版） 拟制:日期：2007-2-13审核:日期： 审核:日期： 批准:日期： 版权所有 ********有限公司
修订纪录
目录 注：Pascal命名法则：即名称中所有单词的第一个字母大写其他字母使用
小写形式。 Camel命名法则：即名称中第一个单词各个字母全部小写，其他部分遵循Pascal命名法则。 1、第一章命名规范 1.1、第一节总则 1．本命名规则除特殊提及外统一使用Camel命名法则。 如：controlMenu 2．命名时尽量不使用拼音，更不可使用拼音缩写（专有名词除外）。 3．如果使用品牌名称命名时其大小写尽量保持和品牌名称一致的样式。 如：LuX则命名时，不要写成LUX，或者Lux，而应该保持与原品牌名称风格一致使用LuX 4．使用专有名词或英文缩写命名时采用大写形式。 如：CNNIC 5．禁止使用仅区分大小写的方式命名。 如：Abc与abc仅用大写A来区分，这样写在类C系语言中不会出错，但是不利于系统的迁移
、第二节变量命名规范 1.2.1、CodeBehind内部命名规范 1．公有字段/属性使用Pascal 命名规则，私有变量/保护变量/局部变量使用Camel命名规则，遵循动宾结构。 例： public class Hello { private string userName; private DateTime loginTime; private bool isOnline; public string UserName { get { return ; } } } 2．即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用意义描述性的名称。仅对于短循环索引使用单字母变量名，如 i 或 j 3．在变量名中使用互补对，如 Min/Max、Begin/End 和 Open/Close。 4．当一个方法内部变量繁多的时候，可以使用Camel命名法则，其中第一个单词可以使用变量类型的缩写来说明以示区别。 例：
代码开发规范
代码开发规范 1 前言 1.1 为什么需要开发规范 编码规范对于程序员而言尤为重要，有以下几个原因： * 一个软件的生命周期中，80%的花费在于维护 * 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护* 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码 * 如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品 1.2 开发规范的作用 * 减少维护花费 * 提高可读性 * 加快工作交接 * 减少名字增生 * 降低缺陷引入的机会
2 命名规范 2.1 常量命名规范 2.1.1 类型 常量命名规范 2.1.2 说明 常量用于保存需要常驻内存中并且经常使用变化不多的数据，定义常量的名称的时候需要遵循望文知意的原则； 2.1.3 规则 1.全部为大写字母； 2.中间以“_”连接； 3.望文知意原则； 2.1.4 备注 代码中涉及到直接使用某个字符串或者其他基本类型的值时，建议定义成常量，避免多处直接使用同样的值作为参数。 2.1.5 举例 ?如：定义一个常量表示最小屏幕宽度的常量，则可以定义一个int类型的常 量，该常量可以命名为：“MIN_SCREEN_WIDTH“； ?其他举例： ?例如：static final int MIN_SCREEN_WIDTH = 4；( √) ?例如：static final int min_screen_width = 4;（×） ?例如：static final int minScreenWidth = 4; （×） ?例如：static final int WIDTH = 4；（×）
程序代码注释编写规范
程序代码注释编写规范 XXX份公司
为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************
安全代码编写规范
安全代码编写规范 一、编写目的 为加强武汉楚烟信息技术有限公司在软件开发中的安全规范要求，减少应用上线后带来潜在的安全风险，特拟定安全代码编写规范。二、使用范围 本规范适用于武汉楚烟信息技术有限公司承建的各类开发类的软件类项目。 三、应用安全设计 在总体架构设计阶段，需明确与客户方沟通确认甲方对于软件安全的相关要求，对于有明确安全要求的（例如授权管理要求、用户认证要求、日志审计要求等），须在设计文档中予以详细说明。对于互联网应用，务必明确网络安全、应用安全、数据安全相关的安全防护手段。 在技术架构上，应采用表现层、服务层、持久层分类的架构，实现对底层业务逻辑进行有效隔离，避免将底层实现细节暴露给最终用户。 在部署架构上，应采用应用服务器、数据库服务器的分离部署模式，在应用服务器被攻击时，不会导致核心应用数据的丢失。如软件产品具备有条件时，应优先采用加密数据传输方式（例如https协议）。 在外部接口设计方面，应采用最小接口暴露的原则，避免开发不必要的服务方法带来相关安全隐患，同时对于第三方接口，应共同商定第三方接入的身份认证方式和手段。
四、应用安全编码 4.1. 输入验证 对于用户输入项进行数据验证，除常见的数据格式、数据长度外，还需要对特殊的危险字符进行处理。特殊字符包括<> " ' % ( ) & + \ \' \"等 对于核心业务功能，除在客户端或浏览器进行数据验证外，还必须在服务器端对数据进行合法性检验，规避用户跳过客户端校验，直接将不合规的数据保存到应用中。 对于浏览器重定向地址的数据，需要进行验证核实，确认重定向地址是否在可信，并且需要对换行符（\r或\n）进行移除或者替换。 4.2. 数据输出 对需要输出到用户浏览器的任何由用户创造的内容，应在输出到浏览器之前或持久化存储之前进行转义(至少对<>转义为< >)以防止跨站攻击脚本(XSS)。对于无法规避的HTML片段提交，需对 嵌套的节点应该缩进; 在属性上使用双引号（字符串拼接除外）; 属性名全小写，用“-”做分隔符; 自动闭合标签处不能使用斜线。
java编程规范+数据库命名规范
Java编程规范 本编程规范建立在标准的Java编程规范的基础上，如和标准的Java编程规范有冲突，以本编程规范为准。 1.1 程序结构 包名 引入包/类名 类注释 类 常量//常量注释 构造器注释 构造器 构造器注释 构造器 方法注释 方法 方法注释 方法 1.2 命名规范 命名规范使得程序更易理解，可读性更强。并且能够提供函数和标识符的信息。 文件命名规范： java程序使用如下的文件名后缀： 文件类型后缀 Java 源文件.java Java 字节码文件.class 对系统的文件命名方式有待于根据实际业务决定。 包命名规范： 包名应该唯一，它的前缀可以为任何小写的ASCII字符，包名按照公司内部的命名规范，这些规范指出了某种目录名，主要包括部门，项目，机器，或者登录名。 命名规则为： app.系统名.模块名.xxx.xxx 包命名举例： app.oa.interceptor.xxx app.oa.sys.xxx 类命名规范： 类名应该是名词，并且是大小写混合的。首字母要大写。尽量保证类名简单并且描述性强。避免使用只取单词首字母的简写或者单词的缩写形式，除非缩写形式比单词的完整形式更常用（例如：URL或者HTML）。文件名必须和public的类名保持一致，注意大小写（JBuilder 等一些编译器可以忽略大小写，要特别注意）。如是实现类命名后缀+Impl。 类命名举例： classLoginAction; classUserServiceImpl; 接口命名规范：
接口命名方式与类命名方式相同。 接口命名举例： interfaceIUserService; interfaceSysYhjsDAO; 方法命名规范； 方法名应该为动词，并且是大小写混合的。首字母要小写，方法名的第 二个单词的第一个字母大写。 方法命名举例： String getNoticeNo(); Collection findByCondition(String); 变量命名规范 变量，以及所有的类实例应为首字母小写的大小写混合形式。变量名的第二个单词 的首字母大写。变量名的首字母不能为下划线或者$符。 变量名应该尽可能的短小，但要有意义。变量名应该便于记忆，也就是说变量名应 该尽可能的做到见名知意。除了暂时使用的变量外（一般用于循环变量），应该避免使 用只有一个字母的变量名。对于临时变量一般说来：i，j，k，m，n代表整型变量。c，d，e代表字符型变量。 变量命名举例： String dataType; String name; inti; char c; 常量命名规范： 声明为类常量的变量或者ANSI常量应该全部为大写字母，并且每个单词间用下划 线“_”隔开。为了便于调试，应避免使用ANSI常量。 常量命名举例： static final int MIN_WIDTH = 4; 1.3 注释规范 Java 提供了两种类型的注释：程序注释和文档注释。程序注释是由分隔符/*…*/，和// 隔开的部分，这些注释和C++ 中的注释一样。文档注释（即“doc 注释”）是Java 独有的。由分隔符/**…*/隔开。使用javadoc工具能够将文档注释抽取出来形成HTML 文件。程序注释主要是对程序的某部分具体实现方式的注释。文档注释是对程序的描述性注释，主要是提供给不需要了解程序具体实现的开发者使用。注释应该是代码的概括性描述，提供不易直接从代码中得到的信息，并且只包含对阅读和理解程序有用的信息。例如注释中包含相应的包如何编译或者在哪个目录下，而不应该包括这个包驻留在哪儿的信息。注释中可以描述一些精妙的算法和一些不易理解的设计思想，但应该避免那些在程序代码中很清楚的表达出来的信息。尽可能的避免过时的信息。错误的注释比没有注释更有害。经常性的注释有时也反映出代码质量的低下。 …程序注释： 程序注释有四种格式：块注释格式，单行注释，跟随注释，行尾注释 ?块注释格式 块注释主要用于描述：文件、方法、数据结构和算法。一般在文件或者方法定义的 之前使用。也可以用在方法定义里面，如果块注释放在函数或者方法定义里，它必须与它所描述的代码具有相同的缩进形式。
FORTRAN 90 程序编程规范
FORTRAN 90 程序编程规范 Fortran 90 编程规范，使程序代码高度组织化，更加易读、易懂、易于维护，程序更加高效。使编出的程序更易懂、易于维护。 1 语言选择 数值预报创新系统软件开发应避免使用Fortran77 的某些过时特征以Fortran 90不一致的特征。选择Fortran 90 作为开发语言，并采用Fortran 90 的新功能，如动态内存的分配(dynamic memory allocation)、递归（recursion ）, 模块(modules)、POINTER 、长变量名、自由格式等。 Fortran 77其中某些只是一些冗余的功能，这些功能已经过时，另外，还有一些在Fortran90 中被证明是不好的用法，建议不要使用。 2 Fortran 90 的新特性 2.1.1 建议使用的Fortran 90 新特性 建议使用Fortran 90 提供的模块（module ），并用Use ONLY 指定module 中哪些变量或派生类型定义可用于调用程序。 尽量使用数组下标三元组，这样可优化并减少所需的代码行数。为提高可读性，要在括号内表明数组的维数，例如： 1dArrayA(:) = 1dArrayB(:) + 1dArrayC(:) 2dArray(: , :) = scalar * Another2dArray(: , :) 当访问数组的子集时，例如在有限差分等式中，可以通过使用下标三元组实现。例如：2dArray(: , 2:len2) = scalar *（ & Another2dArray(:, 1:len2 -1) & - Another2dArray(:, 2:len2) & ) 对程序单元（program units ）命名，并使用End program ，End subroutine ，End interface ，End module 等结构再次指定“program unit ”的名称。 在逻辑表达式中使用>、 >=、 ==、 <、 <=、 /=，它们分别代 替.gt.、.ge.、.eq.、.lt.、.le.、.ne. 。新的表示方法更接近标准的数学符号 在变量定义中始终使用“：：”；始终用“DIMENSION ”定义数组形状；始终用（len=）的语法格式声明字符变量的长度。