编码规范V10.docx
《编码规范V10.docx》由会员分享，可在线阅读，更多相关《编码规范V10.docx（24页珍藏版）》请在冰豆网上搜索。
编码规范V10
编程规范
文档编号：
编码规范
文档信息：
公司级别规范文件
文档名称：
编程规范
文档类别：
工程过程
密级：
内部
版本信息：
1.0
建立日期：
创建人：
审核者：
批准人：
批准日期：
保管人：
存放位置：
文档修订记录
版本编号或者更改记录编号
*变化
状态
简要说明（变更内容和变更范围）
日期
变更人
批准日期
批准人
1．0
A
新增
2014-1-15
彭毅
*变化状态：
A——增加，M——修改，D——删除
文档审批信息
序号
审批人
角色
审批日期
签字
备注
目录
1简介4
1.1目的4
1.2适用范围4
1.3背景描述4
1.4文档结构4
2总则5
3命名规范6
3.1一般命名规范6
3.2特定命名规范7
4文件9
5语句11
5.1package和import11
5.2类和接口11
5.3类型12
5.4变量12
5.5循环12
5.6条件语句14
5.7其他14
6方法14
6.1方法修饰符14
6.2参数规则15
6.3返回值15
6.4内部实现16
7面向对象高级特性16
8结构和注释20
8.1结构20
8.2注释21
9检查清单23
1简介
1.1目的
本文制定的目的是为开发组所有程序员按统一风格、形式编码提供一个标准，从而改进代码的可维护性，提高代码质量。
1.2适用范围
本文档的适用范围为：
Java编码。
1.3背景描述
编码规范对于程序员、整个组织非常的重要：
Ø软件成本的80%来自于维护
Ø几乎没有一个软件从始至终是有一个人维护的
Ø软件规范可以改进代码的可读性，使得程序员能够很快的、彻底的理解新的代码
1.4文档结构
该文挡主要分为两部分：
Java编程所必须遵守的细则和Java代码审查清单。
对于每一条细则包含三项内容：
规范细则简单描述、例子和制定该细则的目的和相关背景知识。
审查清单列出了根据该编程规范进行代码审查时所要检查的内容。
2总则
1）该规范制定的目标是改进程序的可读性，从而提高程序的可理解性、可维护性，提高代码的质量。
从科学的角度来讲，不能期望编码规范涵盖了一种编程语言的方方面面，更多的是具有一种指南、参考的性质，应当允许程序员在编码过程中拥有一定的灵活性。
从管理的角度来讲，制定的标准、规范是必须要严格遵守和执行的，不能随意的篡改或者事实上违背组织已经采用的标准和规范。
因此，程序员在编码过程中应当完全遵守该规范的所有细则，如果在特定的情况下用某种与该规范细则相冲突的形式更有利于程序的可读性，可以考虑保留这种形式，但必须是在经过正式评审、严格控制的情况下实施的。
2）在规范细则描述过程中，必须、应当和可以具有特定的含义。
必须是指必须遵守的细则，应当是指规范推荐的细则，无特殊情况时必须遵守，可以是指规范不禁止但不推荐的细则。
不可以是指必须按要求的去做，不应当是指规范不禁止这么做，但无特殊情况还是不要这么做。
3命名规范
3.1一般命名规范
3.1.1名称
要求：
所有的名称必须用英文书写，不准使用汉语拼音
例子：
zhengzhi//Mustmofityto:
earnValue
背景：
英语是国际化语言
3.1.2包名
要求：
第一个单词必须小写、第二个单词第一个字母需大写
例子：
.iscas.intec.entity.pm
背景：
包名相当于类的命名空间
3.1.3类名
要求：
名词，不同单词之间不可以用任何其他符号进行分隔，每个单词的第一个字母必须大写
例子：
LineLineData
背景：
Java开发的共同约定和Sun核心包的类型命名规范
3.1.4抽象类
要求：
抽象类命名应当遵守类名的要求。
应当在类名前面大写字母Abstract，以明确表示是抽象类。
例子：
AbstractLine
背景：
从名字上就看出是抽象类，更加易读。
3.1.5接口
要求：
接口名称应当遵守类名的要求。
应当在接口名前面加上大写字母I，以明确表示是接口。
例子：
ILineILineData
背景：
明确定义是接口，更加易读一点。
3.1.6方法名称
要求：
方法（构造方法除外）名应当用“动词+名词”、大小写混排的方式命名，起始必须字符小写，方法名称中对象应当是隐含的。
在适当条件下，可以没有名词。
例子：
booleanisSigned（）;
voiddrawLine（）;
line.getLength（）;//ShouldNot:
line.getLineLength（）;
Thread.run（）;//ShouldNot:
runThread（）;
背景：
Java开发的共同约定和Sun核心包的方法命名规范
3.1.7变量名
要求：
变量必须用大小写混排的方式命名，起始字符必须小写。
成员变量可以用下划线开始
例子：
FloatfWidth；
FilePrefixfilePrefix；
背景：
关于变量命名没有一个可以接受的共同标准，变量的命名遵循如下的原则：
Ø标识符应当直观且可以拼读，可望文知意，不必进行“解码”
Ø标识符的长度应当符合“min-length&&max-information”原则
Ø命名规则尽量与所采用的操作系统或开发工具的风格保持一致
Ø程序中不要出现仅靠大小写区分的相似的标识符
Ø程序中不要出现标识符完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但会使人误解
Ø应当避免名字中出现数字编号，如value1,value2。
3.1.8常量命名
要求：
应该全部大写，单词间用下划线隔开。
staticfinal是必须的。
例子：
publicstaticfinalintMIN_WIDTH=4;
背景：
sunjava编码规范。
3.2特定命名规范
3.2.1get/set用法
要求：
成员变量的访问方法应当采用get/set用法，建议采用eclipse的辅助命令生成，尽量不要自己手写。
例子：
employee.getName（）;
matrix.getElement（2,4）;
employee.setName（name）;
matrix.setElement（2,4,value）;
isEnabled（）;
背景：
Java核心包直接访问变量方法的命名规范，在写JavaBean时该规则实际是强制的。
3.2.2is用法
要求：
在Boolean变量命名和访问方法中应当使用is
例子：
isSet,isVisible,isFinished,isFound,isOpen
booleanisAssigned（）;
背景：
Java核心包直接访问变量方法的命名规范，在写JavaBean时该规则实际是强制的。
还可以使用can,has。
3.2.3JFC（JavaSwing）变量
要求：
JFC（JavaSwing）变量应当以变量类型作为后缀
例子：
widthScale,nameJTextField,leftScrollbar,mainJPanel,fileToggle,minLabel
背景：
通过变量名可以得知变量控件类型，从而增强程序的可读性
3.2.4循环变量
要求：
方法内部循环变量应当使用i,j,k（数字），c，d（字符）
背景：
这是一种习惯、简便用法，内部循环变量的作用域有限，比较容易区分。
3.2.5命名缩写
要求：
在变量或者方法名称中，应当避免不通用缩写
例子：
cp insteadof copy
pt insteadof point
comp insteadof compute
背景：
非通用的缩写会影响程序可读性，对于下面比较通用的词语推荐使用缩写
HypertextMarkupLanguage insteadof html
CentralProcessingUnit insteadof cpu
3.2.6否定布尔变量
要求：
不可以出现否定布尔变量
例子：
booleanisError; //NOT:
isNotError
booleanisFound; //NOT:
isNotFound
背景：
在使用！
操作符时，出现双重否定，影响了程序的可读性
4文件
4.1.1行长度
要求：
列数不可以超过80（Eclipse默认的是80）
背景：
编程工具缺省的可见和打印宽度，否则不利于程序的可读性
4.1.2缩进
要求：
4个字符
例子：
背景：
sunjava编码规范，在Eclipse当中默认设置Tab的长度为4个字符：
4.1.3分号
要求：
for循环中的分号应与下一个字符间保留一个空格。
例子：
if（inti=0;i<10;i++）{//错误
if（inti=0;i<10;i++）{//正确，分号之前有空格
背景：
增强代码的可读性
4.1.4逗号
要求：
在声明方法的时候，参数间用逗号格开，逗号应与下一个参数的对象类型名称间间隔一个空格。
例子：
publicStringcreateXML（Stringsql,Connectionconn）{//错误
publicStringcreateXML（Stringsql,Connectionconn）{//正确}
背景：
增强代码的可读性
4.1.5大括号
要求：
{}中的语句应该单独作为一行.}语句应永远单独作为一行。
例子：
if（i>0）{i++};//错误：
{和}在同一行
if（i>0）{
i++；
}//正确：
{单独作为一行
背景：
增强代码的可读性
4.1.6小括号
要求：
在任何时候左括号和后一个字符之间不应该出现空格。
同样,右括号和前一个字符之间也不应该出现空格.不要在语句中使用无意义的括号.括号只应该为达到某种目的而出现在源代码中。
例子：
Integercount=newInteger（sumString）;//错误
Integercount=newInteger（sumString）;//正确
if（（i）=42）{//错误：
括号毫无意义
if（（i==42）or（j==42））｛
｝//正确：
的确需要括号
背景：
良好的使用小括号，能增强代码的可读性。
4.1.7操作符
要求：
操作符（如=、<、<=、>、>=、!
=、+、-、*、/、&&、||等）两边必须各保留一个空格，!
操作符必须在右边保留一个空格。
例子：
str="test";//错误
str="test";//正确：
=两边各有一空格
背景：
增强代码的可读性
4.1.8分行
要求：
分行必须明显
例子：
totalSum=a+b+c+
d+e）;
function（param1,param2,
param3）;
setText（"Longlinesplit"+
"intotwoparts."）;
for（tableNo=0;tableNo tableNo+=tableStep）
背景：
当列数超过80行时应当分行显示，为了增强可读性一般在如下符号后进行换行：
∙逗号
∙操作符
∙后一行和前一行的表达式对齐
5语句
5.1package和import
5.1.1包声明
要求：
包的声明语句必须放在文件开始，每个文件必须属于特定的一个包
背景：
前者是Java所强制规定的，后者有利于使用Java面向对象的技术
5.1.2import语句
要求：
import语句应当不允许用.*import一组java类，不能包含多余的java类。
例子：
importjava.io.*;
import.*;
importjava.rmi.*
importjava.rmi.server.*;
背景：
通过排序和分组可以比较容易分清楚该类基于那些包构建的。
Eclipse使用ctrl+shift+O可以重新组织import。
5.2类和接口
5.2.1类和接口的组织
要求：
类和接口的声明应当按下列方式组织
1.Class/Interfacedocumentation.
2.classorinterfacestatement.
3.Class（static）variablesintheorderpublic,protected,package（noaccessmodifier）,private.
4.Instancevariablesintheorderpublic,protected,package（noaccessmodifier）,private.
5.Constructors.
6.Methods（对于重载的方法，应该按照参数的多少从少到多进行排序）.
背景：
比较容易得找到所要的内容
5.3类型
5.3.1类型转换
要求：
基本类型转换应当明确。
例子：
floatValue=（float）intValue; //NOT:
floatValue=intValue;
背景：
明确的进行类型转换增强程序的可读性。
5.4变量
5.4.1变量类型声明
要求：
变量类型应当和变量的含义保持一致。
例子：
StringisPhase//Wrong
booleanisPhase//Right
背景：
影响程序的可读性。
5.4.2局部变量使用
要求：
变量应当在声明时进行初始化；变量的作用域应当尽可能小。
变量应当避免多次赋值。
变量如果不使用，必须去除。
背景：
对于前者由于Java编译时会检测是否进行了初始化，不会因变量未初始化造成错误，后者有利于程序的可读性
5.4.3类成员变量声明
要求：
类成员变量应当是私有的。
如果不是私有的，必须说明理由。
背景：
将类成员变量公有化会违反面向对象的信息隐藏和封装规则
5.5循环
5.5.1for初始语句
要求：
所有迭代循环都使用for语句来做，不用while,do..while等语句。
循环控制变量之外的其他变量不可以出现在for初始语句中
例子：
sum=0; //NOT:
for（i=0,sum=0;i<100;i++）
for（inti=0;i<100;i++）{ // sum+=value[i];
sum+=value[i];
}
背景：
有利于程序的可读性和可维护性
5.5.2循环控制变量
要求：
在循环控制体内不可以修改循环控制变量。
背景：
导致程序逻辑复杂，带来潜在的问题。
5.5.3do….while语句
要求：
应当使用for语句代替。
背景：
do…while逻辑可以转换为等价的for形式，do…while语句把判断条件放在后面有损程序的可读性
5.5.4break,continue语句
要求：
break,continue语句应当慎用
背景：
break主要用于switch语句，在循环体内不推荐使用break,continue语句，因为它分割了循环基本块，对程序的效率（特别是循环次数比较多）影响比较大。
但对下面的情形可以使用break,continue
for（inti=0;i//Theloopbodyisexecutedonlyonetime
if（sItemNames[i].equals（“Target”））{
//dosomeoperation
break;
}
}
while（i//Theloopbodyisn’texecutedonlyundersomecertainconditions
if（sItemNames[i].equals（“target”））
//dosometime-consumingoperations
continue;
}
5.5.5for（;;）语句
要求：
for（;;）语句应当代替while（true）语句
背景：
后者需要测试是否为真且没有任何意义
5.6条件语句
5.6.1判断条件
要求：
判断条件不可以包含执行语句；复杂判断条件必须避免。
如果要做复杂判断，请用单独的方法来表示。
例子：
file=openFile（fileName,"w"）; //NOT:
if（（file=openFile（filename.
if（file!
=null）｛//"w"））!
=null）{
:
// :
} // }
背景：
重构，提高代码的可读性。
5.6.2if…else语句
要求：
正常的情形应当放在if部分，异常的部分应当放在else部分
例子：
booleanisSuccess=readFile（fileName）;
if（isSuccess）{
//Normaloperations
}else{
//Exceptionaloperations
}
背景：
有利于程序的可读性，符合正常的思维习惯
5.7其他
5.7.1常数
要求：
除0,1外的数必须避免在程序中出现
背景：
MagicNumber。
在程序中直接写数字，严重影响程序的可读性和可维护性
6方法
6.1方法修饰符
要求：
方法修饰符应当按如下顺序书写：
staticabstractsynchronizedfinalnative
背景：
指public、private、package、protected，指volatile、transient
6.2参数规则
6.2.1参数命名
要求：
参数名应当完整，缩写应当遵循缩写规则。
例子：
voidsetValue（intw,inth）;//NotGoodStyle
voidsetValue（intwidth,intheight）;//GoodStyle
背景：
有利于程序的可读性
6.2.2参数顺序
要求：
参数顺序应当合理
例子：
对于subString函数。
一般开始在前，结束在后。
voidsubString（intbeginIndex,intendIndex）;
背景：
符合阅读和思考习惯。
6.2.3参数个数
要求：
方法的参数个数必须小于等于5。
无用的参数必须去掉。
背景：
方法参数太多不利于调用和理解，容易出错。
超过5个需要将参数封装起来。
6.3返回值
6.3.1返回值类型
要求：
方法名字和返回值的类型不可以冲突
例子：
intgetUserName（）;//Badstyle
StringgetUserName（）;//Goodstyle
背景：
调用方法时容易产生歧义和错误。
6.3.2附加返回值
要求：
考虑程序的灵活性，可以在不明确需要返回值的情况下返回一个引用
例子：
StringBuffer.append（Strings）;
背景：
可以用于连接操作。
6.4内部实现
6.4.1参数检查
要求：
方法必须对传进来的参数进行必要的检验。
参数是否为null，由方法的调用者来进行保证。
对于允许参数为null的情况，必须在方法的JAVADOC中进行说明。
对于输入参数的范围有严格要求的话，必须在方法实现中进行检查。
背景：
提高程序的健壮性
6.4.2方法功能
要求：
方法的功能应当单一。
背景：
方法功能过多不利于维护和编写，可能会产生很多副作用。
6.4.3方法规模
要求：
方法的规模一般应当控制在50行以内（不能超过一屏）
背景：
便于方法的编写、测试和维护
6.4.4static局部变量
要求：
方法中不可以出现局部静态变量
背景：
局部静态变量导致程序具有记忆的功能，程序的状态不可预测
6.4.5异常处理
要求：
catch语句中必须有异常处理代码，异常不可以被忽略。
背景：
提高程序的健壮性，防止异常被隐藏、增加调试的难度
7面向对象高级特性
7.1.1私有对象
要求：
对不可以实例化的类，可以声明私有的缺省构造函数
背景：
控制对某些的类的访问
7.1.2Re-inheritance
要求：
Re-inheritance不可以出现
例子：
publicinterfaceColorable{
intRED=0xff0000,GREEN=0x00ff00,BLUE=0x0000ff;
}
publicinterfacePaintableextendsColorable{
intMATTE=0,GLOSSY=1;
}
classPoint{intx,y;}
classColoredPointextendsPointimplementsColorable{
...
}
classPaintedPointextendsColoredPointimplementsPaintable{
...RED...
}
背景：
re-inheritance不会出现错误，但类间的关系过于晦涩。
类之间的关系应当尽量简单。
7.1.3Multi-inheritance
要求：
变量多继承不可以出现
例子：
interfaceFrob{floatv=2.0f;}
classSuperTest{intv=3;}
classTestextendsSuperTestimplementsFrob{
publicstaticvoidmain（String[]args）{
newTest（）.printV（）;
}
voidprintV（）{System.out.println（v）;}
}
背景：
多重变量继承因为命名冲突不便于程序编写和可读。
7.1.4变量隐藏
要求：
变量隐藏不可以出现
例子：
classPoint{
升级会员 