老徐1 简介
对于软件开发遵循统一的规范，有利于增强代码的可读性，同时防范错误，更好的发挥所使用的语言的优点，提高工作效率。所以我们制定此编程规范，指导公司的编码活动。本规范适用于公司各个使用Java作为开发语言的项目，作为源程序编写的规范，必须遵守。使用其他语言所编写的程序，比如Perl，在不和所使用的语言冲突的情况下，可以参考本规范的要求来编写源程序。
参考资料
| 文档名称 | 作者 | 发布日期 |
|---|---|---|
| 《Rational Unified Process 2000》 | Rational Software Corporation | |
| 《C++编程规范》 | 摩托罗拉中国公司 | |
| 《高质量C语言编程》 | 林锐 | |
| 《Java编程规范》 | Sun |
2 文件和目录
2.1 文件使用统一而且通用的后缀名
- java程序的源文件： .java
- 二进制文件： .class
- AspectJ源文件: .aj
2.2 文件名要清晰、精炼、避免冲突
可以用公共前缀对文件分组，但是要防止名字过长和冗余信息过多。在一个项目中，遵循统一的文件名命名规则。
2.3 文件/目录名字字符集选择
- 只能使用以下字符集：[A-Za-z0-9_-]
- 包名只能用小写字符、数字和“.”。
- 类名第一个字符必须大写。
2.4 单个的文件建议不超过1000行
这项不作为强制条件执行，但一个类超过1000行，很有可能这个类的内聚性有问题。
2.5 单个的函数建议不超过100行，但一定不要超过200行
3 文件组织
每个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件（不建议）。公共类必须是这个文件中的第一个类或接口。 Java源文件还遵循以下规则：
- 文件头注释
- 包和引入语句
- 类和接口声明
3.1 文件头注释
参见注释里的文件头注释。
3.2 包和引入语句
在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。例如：
package java.awt;
import java.awt.peer.CanvasPeer;3.3 类和接口说明
类/接口申明包括以下几部分：
- 1. 类/接口文档注释
- 2. 类或接口的声明
- 3. 类/接口实现的注释（该注释应包含任何有关整个类或接口的信息，而这些信息又不适合）
- 4. 类的(静态)变量
- 5. 实例变量
- 6. 构造器
- 7. 方法
3.4 变量申明的次序
变量申明的次序如下：
- 1. 先静态后实例变量
- 2. 先public后protected再private
4 排版
4.1 缩进
4个空格作为缩进排版的一个单位，缩进也可以使用TAB键。
4.2 在程序适当的地方加入空行
在以下地方应该是用空行分开：
- 1. 方法之间应该用空行分开；
- 2. 一组局部变量声明和代码之间用空行分开；
- 3. 用空行将代码按照逻辑片断划分；
- 4. 除非方法非常简单（如只有一两条语句），否则方法返回语句和其他语句用空行分开；
- 5. 每个类声明之后应该加入空行同其他代码分开；
4.3 换行
每一行不要超过120个字符，当一个表达式无法容纳在一行内时，可以依据如下规则分行书写：
- 1. 在一个逗号后面断开
- 2. 在一个操作符前面断开
- 3. 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开
- 4. 新的一行应该与上一行同一级别表达式的开头处对齐
- 5. 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进4个空格。
示例:
以下是断开方法调用的一些例子:
foo.sum(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = foo.sum(longExpression1,
foo.sum(longExpression2,
longExpression3));
以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开，后者不建议采用。
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6;
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; 以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进4个空格。
//常规情形
public synchronized void invoke (int anArg, Object anotherArg,
String yetAnotherArg,
Object andStillAnother)
{
...
}
//缩进4个空格以免太靠右
public synchronized void invoke (int anArg, Object anotherArg,
String yetAnotherArg, Object andStillAnother)
{
...
} 4.4 一行只写一条语句
示例:
如下例子不符合规范:
rect.length = 0; rect.width = 0;应如下书写:
rect.length = 0;
rect.width = 0;4.5 if for do while等语句自占一行，其后无论执行语句多长，都应该使用{}
例外的情况是：如果存在多个if…else…语句并列，则else可以和if放在同一行。
示例：
如下的写法不合规范：
if (0 == a) return null;应该这样写：
if (0 == a)
{
return null;
}4.6 右大括号}要单独占一行，左大括号不作结强制规定，但在单个文件中要统一
右大括号要单独占一行，并且和它的控制语句有相同的缩进。但也有例外：
* 1. do-while循环中，}和while放在一行,应该按照以下格式书写：
do
{
i++;
} while (i < 100);4.7 代码行之间应该留有适当的空格
代码行内应该适当的使用空格，具体地说来：
- 1. 关键字之后要留空格。象final、virtual、synchronized、case 等关键字之后至少要留一个空格，否则无法辨析关键字。象if、for、while 等关键字之后应留一个空格再跟左括号‘（’，以突出关键字。
- 2. 方法名之后不要留空格，紧跟左括号‘（’，以与关键字区别。
- 3. ‘（’向后紧跟，‘）’、‘，’、‘;’向前紧跟，紧跟处不留空格。
- 4. ‘，’之后要留空格，如function(int x, int y, int z)。如果‘;’不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。
- 5. 值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”、“?”等二元操作符的前后应当加空格。
- 6. 一元操作符如“!”、“~”、“++”、“--”等前后都不加空格。
- 7. 象“［］”、“.”这类操作符前后不加空格。
示例,应该按照以下的格式书写：
void foo()
{
//…
}或者：
if (0 == i)
{
//…
}或者：
foo.bar或者
foo[bar]或者：
i++;
!i;或者
i += 9;
a * b;等等
5 命名规范
5.1 命名基本规范
命名应该遵守以下基本原则：
- 1. 命名要简单清楚，避免使用引起误解的词汇，避免使用模糊的缩写，长度不要超过25个字符
- 2. 命名必须使用英文单词，不能使用汉语拼音
- 3. 命名用可发音的名字
- 4. 选择通用词汇并且贯穿始终
- 5. 命名要通俗易懂
另外，命名还应该做到：
- 1. Package 的名字应该都是由一个全部小写单词组成。
- 2. Class 的名字必须由大写字母开头而其他字母都小写的单词组成
- 3. 变量的名字必须用一个全部小写的单词开头。后面的单词用大写字母开头，其余都小写。
- 4. 参数的名字必须和变量的命名规范一致。
- 5. 数组应该总是用下面的方式来命名：
byte[] buffer; 而不是：
byte buffer[]; - 6. 使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：
setCounter(int count)
{
this. count = count;
}5.2 类名采用每个单词首字母大写的方式
对于首字母缩写词如HTTP，把它同普通单词一样处理即仅有第一个H大写，其余字母小写。
5.3 包的命名格式采用utn.xxx开头
所有包的命名必须以utn.xxx开头，xxx代表项目或产品的简称。
5.4 常量、静态变量名采用全大写的方式，每个单词间用下划线分隔
这里的常量一般指类里用final static 修饰的成员变量。
5.5 变量名和方法名第一个单词的首字母小写，其余每个单词的首字母大写，首字母以外的字母全部小写
对于首字母缩写词如HTTP，把它同普通单词一样处理即仅有第一个H大写，其余字母小写。
6 注释
6.1 确保注释是完善你的代码而不是重复它
注释不应该包含代码本身显而易见的信息，而应该给出其他有用的信息。不仅要说明程序作了什么，还应该说明原因。
6.2 用中文或者英文注释代码
如果我们使用的开发平台支持中文，则尽可能的使用中文；否则使用流利的英语。
6.3 注释用词要精确，不能有二义性
人与人交流最大的问题就是误解。你以为他们看懂了你的注释或者他们认为自己看懂了你的注释，实际上往往并非如此，所以对于注释要和代码一样的进行审查。
6.4 注释中的术语要通用
6.5 注释应该和代码同步更新
6.6 禁止使用行尾注释
禁止采用行尾注释方法
int timeLength; //表示经历时间的长度使用以下的注释方法
//表示经历时间的长度
int timeLength;
或者这个变量非常重要，可以使用文档注释：
/**
* 表示经历时间的长度
*/
int timeLength；6.7 注释不要嵌套
6.8 使用文档注释
如果你使用Java语言编程，你必须使用Javadoc的文档格式进行注释，以便以后用javadoc生成相应的文档。
必须使用文档注释的地方有：文件头注释、类定义注释、方法注释、方法或者类内部重要的变量。
6.9 文件头注释
使用Java编程的时候，在每个源程序文件的头部进行如下的注释：
/**
* @author Tom
* @version 1.0 2002/10/28
*
* Copyright (C) 2000, 2002, KOAL, Inc.
*
*/注意文件头注释为javadoc的文档注释类型，下面的方法、类和结构的注释也是使用javadoc的文档注释类型。
如果注释的内容超过一行，缩进也是四个空格。
在整个文件头注释结束后至少留两个空行。
注意版权一行，前一个时间是文件产生的年份，后一个是最后修改的年份。
上面的示例列出的是最少的注释内容，如果有别的内容，只要有必要，就可以添加在注释中，但一定要保证注释的排版清楚，不会造成阅读上的不便。下面的方法注释、类注释也可以是同样处理。
6.10 方法注释
使用Java编程的时候，每一个方法开头要有如下的注释：
/**
* <func-name>：<对方法的简单描述>
*
* @param <方法参数> <对方法参数的简单描述>
* @return <方法的返回值> <对返回值的简单描述>
* @throws <抛出的异常><抛出的异常的描述>
*
* @see <参见的内容>
* @deprecated <删除的内容>
*/如果方法没有返回值，则这样书写：@return void，如果方法没有参数或者异常抛出，@param和@throws可以省略。@see和@deprecated标签只在必要的时候使用就可以了。
6.11 类注释
使用Java编程的时候，每一个类开头要有如下的注释：
/**
* <class-type> <class-name>：<对这个类的简单描述>
*
* @see
* @deprecated
*/其中class-type说明这是个类， interface等，@see和@deprecated标签只在必要的时候使用就可以了。
6.12 方法或者类的内部注释
在方法或者类的内部，可以不使用文档注释，对于非常重要的变量或者语句，可以使用文档注释，对于一般性的说明文字，使用普通的注释就可以了。
6.13 代码修改必须增加注释
必须在修改的地方说明以下内容：
- 1. 什么时间修改
- 2. 谁修改
- 3. 修改了什么内容
- 4. 到哪里为至
- 5. 修改后的版本号（产品版本或项目代码）
增加代码的注释方法:
…..
//V1.3.1 2006-6-21 zhangsan 增加代码的原因 +{{
增加的代码
//}}删除代码的注释方法:
…..
/*V1.3.1 2006-6-21 zhangsan 删除代码的原因 -{{
被删除的代码
}}*/修改代码的注释方法:
…..
/*V1.3.1 2006-6-21 zhangsan 修改代码的原因 c{{
被删除的代码
*/
新改动的代码
//}}