...//programcode
}
publicstaticLogIteratorread(StringlogType,DatestartTime,DateendTime,
intlogLevel,StringuserName,intbufferNum)
3.1.4.*不允许把多个短语句写在一行中,即一行只写一条语句
示例:
如下例子不符合规范。
LogFilenamenow=null;LogFilenamethat=null;
应如下书写:
LogFilenamenow=null;
LogFilenamethat=null;
3.1.5.*if,for,do,while,case,switch,default等语句自占一行,且if,for,do,while等语句的执行语句无论多少都要加括号{}。
示例:
如下例子不符合规范。
if(writeToFile)writeFileThread.interrupt();
应如下书写:
if(writeToFile){
writeFileThread.interrupt();
}
3.1.6.*相对独立的程序块之间、变量说明之后必须加空行。
示例:
如下例子不符合规范。
if(log.getLevel()return;
}
LogWriterwriter;
应如下书写:
if(log.getLevel()return;
}
LogWriterwriter;
intindex;
3.1.7.*在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如.),后不应加空格。
说明:
采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在Java语言中括号已经是最清晰的标志了。
在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。
给操作符留空格时不要连续留两个以上空格。
示例:
(1)逗号、分号只在后面加空格。
inta,b,c;
(2)比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格。
if(current_time>=MAX_TIME_VALUE)
a=b+c;
a*=2;
a=b^2;
(3)"!
"、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格。
flag=!
isEmpty;//非操作"!
"与内容之间
i++;//"++","--"与内容之间
(4)"."前后不加空格。
p.id=pid;//"."前后不加空格
(5)if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
if(a>=b&&c>d)
3.2.建议
类属性和类方法不要交叉放置,不同存取范围的属性或者方法也尽量不要交叉放置。
格式:
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
4.注释规范
4.1.规则
4.1.1.一般情况下,源程序有效注释量必须在30%以上。
说明:
注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
可以用注释统计工具来统计。
4.1.2.包的注释:
包的注释写入一名为package.html的HTML格式说明文件放入当前路径。
说明:
方便JavaDoc收集
示例:
com/chinasofti/javacode/dao/package.html
4.1.3.包的注释内容:
简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
说明:
在详细描述中应该说明这个包的作用以及在整个项目中的位置。
格式:
一句话简述。
详细描述。
产品模块名称和版本
公司版权信息
示例:
为Service包提供数据操作服务,上层业务使用本包的类操作数据。
详细描述。
。
。
。
。
。
。
。
DaoV100R001
(C)版权所有2015-2016武汉中软卓越科技有限公司
4.1.4.文件注释:
文件注释写入文件头部,包名之前的位置。
说明:
注意以/*开始避免被JavaDoc收集
示例:
/*
*注释内容
*/
packagecom.chinasofti.javacode.dao;
4.1.5.文件注释内容:
版权说明、描述信息、生成日期、修改历史。
说明:
文件名可选。
格式:
/*
*文件名:
[文件名]
*版权:
〈版权〉
*描述:
〈描述〉
*修改人:
〈修改人〉
*修改时间:
YYYY-MM-DD
*修改单号:
〈修改单号〉
*修改内容:
〈修改内容〉
*/
说明:
每次修改后在文件头部写明修改信息,CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。
在代码受控之前可以免去。
示例:
/*
*文件名:
ProductDao.java
*版权:
Copyright2015-2016CS&SCo.Ltd.AllRightsReserved.
*描述:
DaoV100R001系统
*修改人:
张三
*修改时间:
2016-02-16
*修改内容:
新增
*修改人:
李四
*修改时间:
2016-02-26
*修改单号:
CSB368
*修改内容:
。
。
。
。
。
。
*修改人:
王五
*修改时间:
2006-03-25
*修改单号:
CSB498
*修改内容:
。
。
。
。
。
。
*/
4.1.6.类和接口的注释:
该注释放在package关键字之后,class或者interface关键字之前。
说明:
方便JavaDoc收集。
示例:
packagepackagecom.chinasofti.javacode.dao;
/**
*注释内容
*/
publicclassStudentDao
4.1.7.类和接口的注释内容:
类的注释主要是一句话功能简述、功能详细描述。
说明:
可根据需要列出:
版本号、生成日期、作者、内容、功能、与其它类的关系等。
如果一个类存在Bug,请如实说明这些Bug。
格式:
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@author[作者]
*@version[版本号,YYYY-MM-DD]
*@see[相关类/方法]
*@since[产品/模块版本]
*@deprecated
*/
说明:
描述部分说明该类或者接口的功能、作用、使用方法和注意事项,每次修改后增加作者和更新版本号和日期,@since表示从那个版本开始就有这个类或者接口,@deprecated表示不建议使用该类或者接口。
示例:
/**
*StudentDao类提供对Student类数据读写的操作。
*@author张三,李四,王五
*@version1.2,2006-03-25
*@seeStudent
*@seeStudentService
*@sinceStudentService1.0
*/
4.1.8.类属性、公有和保护方法注释:
写在类属性、公有和保护方法上面。
示例:
/**
*注释内容
*/
privateStringname;
/**
*注释内容
*/
publicvoiddelete(intid)
4.1.9.成员变量注释内容:
成员变量的意义、目的、功能,可能被用到的地方。
4.1.10.公有和保护方法注释内容:
列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式:
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@param[参数1][参数1说明]
*@param[参数2][参数2说明]
*@return[返回类型说明]
*@exception/throws[违例类型][违例说明]
*@see[类、类#方法、类#成员]
*@deprecated
*/
说明:
@since表示从那个版本开始就有这个方法;@exception或throws列出可能仍出的异常;@deprecated表示不建议使用该方法。
示例:
/**
*根据提供的学生Id值删除学生数据。
Id值不存在时,不做任何操作。
*@paramid学生Id值(唯一)
*@return无
*@sinceStudentService1.0
*/
publicvoiddelete(intid)
4.1.11.对于方法内部用throw语句抛出的异常,必须在方法的注释中标明,对于所调用的其他方法所抛出的异常,选择主要的在注释中说明。
对于非RuntimeException,即throws子句声明会抛出的异常,必须在方法的注释中标明。
说明:
异常注释用@exception或@throws表示,在JavaDoc中两者等价,但推荐用@exception标注Runtime异常,@throws标注非Runtime异常。
异常的注释必须说明该异常的含义及什么条件下抛出该异常。
4.1.12.*注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
4.1.13.*注释与所描述内容进行同样的缩排。
说明:
可使程序排版整齐,并方便注释的阅读与理解。
示例:
如下例子,排版不整齐,阅读稍感不方便。
publicvoidexample(){
//注释
CodeBlockOne
//注释
CodeBlockTwo
}
应改为如下布局。
publicvoidexample(){
//注释
CodeBlockOne
//注释
CodeBlockTwo
}
4.1.14.*将注释与其上面的代码用空行隔开。
示例:
如下例子,显得代码过于紧凑。
//注释
programcodeone
//注释
programcodetwo
应如下书写:
//注释
programcodeone
//注释
programcodetwo
4.1.15.*对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。
说明:
这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。
4.1.16.*对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
说明:
这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。
4.1.17.*边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
不再有用的注释要删除。
4.1.18.*注释的内容要清楚、明了,含义准确,防止注释二义性。
说明:
错误的注释不但无益反而有害。
4.1.19.*避免在注释中使用缩写,特别是不常用缩写。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
4.2.建议
4.2.1.*避免在一行代码或表达式的中间插入注释。
说明:
除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
4.2.2.*通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
说明:
清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
4.2.3.*在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说明:
注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
示例:
如下注释意义不大。
//如果deleteFlag为真
if(receiveFlag)
而如下的注释则给出了额外有用的信息。
//如果该数据是已标识为删除的数据
if(deleteFlag)
4.2.4.*在程序块的结束行右方加注释标记,以表明某程序块的结束。
说明:
当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
示例:
参见如下例子。
if(...){
programcode1
while(indexprogramcode2
}//endofwhile(index}//endofif(...)//指明是哪条if语句结束
4.2.5.*注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达。
说明:
注释语言不统一,影响程序易读性和外观排版,出于维护的考虑,建议使用中文。
4.2.6.方法内的单行注释使用//。
说明:
调试程序的时候可以方便的使用/*。
。
。
*/注释掉一长段程序。
4.2.7.注释尽量使用中文注释和中文标点。
方法和类描述的第一句话尽量使用简洁明了的话概括一下功能,然后加以句号。
接下来的部分可以详细描述。
说明:
JavaDoc工具收集简介的时候使用选取第一句话。
4.2.8.顺序实现流程的说明使用1、2、3、4在每个实现步骤部分的代码前面进行注释。
示例:
如下是对设置属性的流程注释
//1、判断输入参数是否有效。
。
。
。
。
。
//2、设置本地变量。
。
。
。
。
。
。
4.2.9.一些复杂的代码需要说明。
示例:
这里主要是对闰年算法的说明。
//1.如果能被4整除,是闰年;
//2.如果能被100整除,不是闰年.;
//3.如果能被400整除,是闰年.。
5.命名规范
5.1.规则
5.1.1.包名采用域后缀倒置的加上自定义的包名,采用小写字母。
在部门内部应该规划好包名的范围,防止产生冲突。
部门内部产品使用部门的名称加上模块名称。
产品线的产品使用产品的名称加上模块的名称。
格式:
com.chinasofti.产品名.模块名称
com.chinasofti.部门名称.项目名称
示例:
数据操作层模块包名com.chinasofti.javacode.dao
实体层模块包名com.chinasofti.javacode.entity
5.1.2.类名和接口使用类意义完整的英文描述,每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。
示例:
StudentDao,ProductDao,ConfigManager,LogConfig
5.1.3.方法名使用类意义完整的英文描述:
第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
示例:
privatevoidgetStudents();
publicvoidaddNewOrder();
5.1.4.方法中,存取属性的方法采用setter和getter方法,动作方法采用动词和动宾结构。
格式:
get+非布尔属性名()
is+布尔属性名()
set+属性名()
动词()
动词+宾语()
示例:
publicStringgetType();
publicbooleanisFinished();
publicvoidsetVisible(boolean);
publicvoidshow();
publicvoidaddKeyListener(Listener);
5.1.5.属性名使用意义完整的英文描述:
第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
属性名不能与方法名相同。
示例:
privatecustomerName;
privateorderNumber;
privatesmpSession;
5.1.6.常量名使用全大写的英文描述,英文单词之间用下划线分隔开,并且使用finalstatic修饰。
示例:
publicfinalstaticintMAX_VALUE=1000;
publicfinalstaticStringDEFAULT_START_DATE="2005-12-08";
5.1.7.属性名可以和公有方法参数相同,不能和局部变量相同,引用非静态成员变量时使用this引用,引用静态成员变量时使用类名引用。
示例:
publicclassPerson
{
privateStringname;
privatestaticListproperties;
publicvoidsetName(Stringname)
{
this.name=name;
}
publicvoidsetProperties(Listproperties)
{
Person.properties=properties;
}
}
5.2.建议
5.2.1.常用组件类的命名以组件名加上组件类型名结尾。
示例:
Application类型的,命名以App结尾——MainApp
Frame类型的,命名以Frame结尾——TopoFrame
Panel类型的,建议命名以Panel结尾——CreateCircuitPanel
Bean类型的,建议命名以Bean结尾——DataAccessBean
EJB类型的,建议命名以EJB结尾——DBProxyEJB
Applet类型的,建议命名以Applet结尾——PictureShowApplet
5.2.2.如果函数名超过15个字母,可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。
示例:
getCustomerInformation()改为getCustomerInfo()
5.2.3.准确地确定成员函数的存取控制符号,不是必须使用public属性的,请使用protected,不是必须使用protected,请使用private。
示例:
protectedvoidsetUserName(),privatevoidcalculateRate()
5.2.4.含有集合意义的属性命名,尽量包含其复数的意义。
示例:
customers,orderItems
6.编码规范
6.1.规则
6.1.1.*明确方法功能,精确(而不是近似)地实现方法设计。
一个函数仅完成一件功能,即使简单功能也应该编写方法实现。
说明:
虽然为仅用一两行就可完成的功能去编方法好象没有必要,但用方法可使功能明确化,增加程序可读性,亦可方便维护、测试。
6.1.2.应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责,缺省是由方法调用者负责。
说明:
对于模块间接口方法的参数的合法性检查这一问题,往往有两个极端现象,即:
要么是调用者和被调用者对参数均不作合法性检查,结果就遗漏了合法性检查这一必要的处理过程,造成问题隐患;要么就是调用者和被调用者均对参数进行合法性检查,这种情况虽不会造成问题,但产生了冗余代码,降低了效率。
6.1.3.明确类的功能,精确(而非近似)地实现类的设计。
一个类仅实现一组相近的功能。
说明:
划分类的时候,应该尽量把逻辑处理、数据和显示分离,实现类功能的单一性。
示例:
数据类不能包含数据处理的逻辑。
通信类不能包含显示处理的逻辑。
6.1.4.所有的数据类必须重载toString()方法,返回该类有意义的内容。
说明:
父类如果实现了比较合理的toString(),子类可以继承不必再重写。
示例:
publicTopoN