软件编程规范Java.docx
- 文档编号:7111221
- 上传时间:2023-01-18
- 格式:DOCX
- 页数:37
- 大小:63.01KB
软件编程规范Java.docx
《软件编程规范Java.docx》由会员分享,可在线阅读,更多相关《软件编程规范Java.docx(37页珍藏版)》请在冰豆网上搜索。
软件编程规范软件编程规范Java本资料仅供内部使用!
软件编程规范Java东南融通集团2011年1月8日本文件中出现的任何文字叙述、文档格式、插图、照片、方法、过程等内容,除另有特别注明,版权均属东南融通系统工程有限公司所有,受到有关产权及版权法保护。
任何个人、机构未经东南融通系统工程有限公司的书面授权许可,不得以任何方式复制或引用本文件的任何片断。
修改记录制定日期生效日期制定/修订内容摘要页数版本拟稿审查批准2011-1-82011-1-8指定1.0孟令澎1.1.1目目录录目录I前言11基本原则12文件结构12.1基本格式12.2对齐12.3空行空格12.4断行13注释14命名规则15声明16表达式与语句17类和接口1附录1附录A编程模版11.1.2前前言言软件编程规范的目的是为了统一公司软件编程风格,提高软件源程序的可读性、可靠性和可重用性,提高软件源程序的质量和可维护性,减少软件维护成本,最终提高软件产品生产力。
本规范是针对JAVA语言的编程规则。
本规范适用于公司所有产品的软件源程序,同时考虑到不同产品和项目的实际开发特性,本规范分成规则性和建议性两种:
对于规则性规范,要求所有软件开发人员严格执行;对于建议性规范,各项目编程人员可以根据实际情况选择执行。
本规范的示例都以JAVA语言描述。
本规范的内容包括:
基本原则、文件结构、注释、命名规则、声明、表达式与语句、类和接口等。
规范最后给出了标准模板供软件人员参考。
本规范自生效日期起,对以后新编写的和修改的代码有约束力。
对以前的代码不要求进行修改。
对于由开发工具自动生成的代码可以不约束。
对本规范中所使用的术语解释如下:
原则:
编程时应该坚持的指导思想。
规则:
编程时必须遵守的约定。
建议:
编程时必须加以考虑的约定。
说明:
对此规则或建议的必要的解释。
正例:
对此规则或建议给出的正确例子。
反例:
对此规则或建议给出的反面例子。
2011年1月8日1.1.31基本原则【原则1-1】首先是为人编写程序,其次才是计算机。
说明:
这是软件开发的基本要点,软件的生命周期贯穿产品的开发、测试、生产、用户使用、版本升级和后期维护等长期过程,只有易读、易维护的软件代码才具有生命力。
【原则1-2】保持代码的简明清晰,避免过分的编程技巧。
说明:
简单是最美。
保持代码的简单化是软件工程化的基本要求。
不要过分追求技巧,否则会降低程序的可读性。
【原则1-3】所有的代码尽量遵循SUN的CodeConventionsfortheJavaTMProgrammingLanguage标准(参见:
http:
/1-4】编程时首先达到正确性,其次考虑效率。
说明:
编程首先考虑的是满足正确性、健壮性、可维护性、可移植性等质量因素,其次考虑程序的效率和资源占用。
【原则1-5】保持一致性,尽可能多的使用相同的规则。
【原则1-6】尽可能复用、修正原有的代码。
说明:
尽量选择可借用的代码,对其修改优化以达到自身要求。
【原则1-7】尽量减少同样的错误出现的次数。
说明:
事实上,我们无法做到完全消除错误,但通过不懈的努力,可以减少同样的错误出现的次数。
1.1.42文件结构文件结构程序布局的目的是显示出程序良好的逻辑结构,提高程序的准确性、连续性、可读性、可维护性。
更重要的是,统一的程序布局和编程风格,有助于提高整个项目的开发质量,提高开发效率,降低开发成本。
同时,对于普通程序员来说,养成良好的编程习惯有助于提高自己的编程水平,提高编程效率。
因此,统一的、良好的程序布局和编程风格不仅仅是个人主观美学上的或是形式上的问题,而且涉及到产品质量,涉及到个人编程能力的提高,必须引起大家重视。
1.1.4.12.1基本格式基本格式【规则2-1-1】源代码文件(.java)的布局顺序是:
包、import语句、注释、类。
正例:
packagecom.longtop;importjava.awt.peer.CanvasPeer;importjava.io.*;importcom.longtop.ums.uep.*;/*文件名称:
题目名称*文件描述:
本类描述*版权所有:
版权所有(C)2011*公司:
东南融通系统工程(北京)有限公司*内容摘要:
/简要描述本文件的内容,包括主要模块、函数及其功能的说明*其他说明:
/其它内容的说明*完成日期:
/输入完成日期,例:
2011年2月25日*修改记录1:
/修改历史记录,包括修改日期、修改者及修改内容*修改日期:
*版本号:
*修改人:
*修改内容:
*修改记录2:
*version1.0*author作者姓名*/publicclassClassName【规则2-1-2】遵循统一的布局顺序来书写import语句,不同类别的import语句之间用空行分隔。
说明:
package语句其后可跟import语句,而且与package间隔一个空行。
import包的排列顺序为java开头的包在最前面,接下来是引自外部的包,再接下来是应用程序自身的包,即import中标准的包名要在本地的包名之前,而且按照字母顺序排列。
正例:
packagecom.zte;importjava.awt.peer.CanvasPeer;/java自身的包importjava.io.*;importcom.klg.field.*;/第三方的包importcom.zte.ums.uep.*;/程序自身的包【规则2-1-3】程序中一行的代码和注释不能超过120列。
说明:
包括空格在内不超过120列。
【规则2-1-4】if、else、elseif、for、while、do等语句独占一行,执行语句不得紧跟其后。
不论执行语句有多少都要加。
说明:
这样可以防止书写失误,也易于阅读。
正例:
if(varible1varible2)varible1=varible2;反例:
下面的代码执行语句紧跟if的条件之后,而且没有加,违反规则。
if(varible1varible2)varible1=varible2;建议2-1-1源程序中关系较为紧密的代码应尽可能相邻。
说明:
这样便于程序阅读和查找。
正例:
length=10;width=5;/矩形的长与宽关系较密切,放在一起。
strCaption=“Test”;反例:
length=10;strCaption=“Test”;width=5;1.1.4.22.2对齐对齐【规则2-2-1】一般禁止使用制表符,必须使用空格进行缩排。
缩进为4个空格。
说明:
对于利用JBuilder等编程工具的,可以设置TAB键为4个空格代替。
消除不同编辑器对制表符处理的差异。
【规则2-2-2】程序的分界符和应独占一行,同时与引用它们的语句左对齐。
之内的代码块使用缩进规则对齐。
说明:
这样使代码便于阅读,并且方便注释。
dowhile语句可以例外,while条件可与在同一行。
正例:
voidfunction(intvar)while(condition)doSomething();/与缩进4格/与引用它们的模块左对齐反例:
voidfunction(intvar)while(condition)doSomething();【规则2-2-3】多维的数组如果在定义时初始化,按照数组的矩阵结构分行书写。
正例:
intnumber=1,1,1,2,4,8,3,9,27,4,16,64;【规则2-2-4】相关的赋值语句等号对齐。
正例:
width=50;length=20;height=40;1.1.4.32.3空行空格空行空格【规则2-3-1】不同逻辑程序块之间要使用空行分隔。
说明:
空行起着分隔程序段落的作用。
适当的空行可以使程序的布局更加清晰。
正例:
voiddoSomething()/doSomething实现代码/空一行voiddoOtherThing()doOtherThing实现代码反例:
voiddoSomething()doSomething实现代码voiddoOtherThing()doOtherThing实现代码/两个函数的实现是两个逻辑程序块,应该用空行加以分隔。
【规则2-3-2】一元操作符如“+”、“-”、“!
”、“”、(类型)等前后不加空格。
“”“.”这类操作符前后不加空格。
正例:
!
valuevalue+countnumberi=5;box.getWidth();【规则2-3-3】多元运算符和它们的操作数之间至少需要一个空格。
说明:
空格的多少根据上下文调整。
正例:
value=oldValue;total+valuenumber+=2;【规则2-3-4】方法名之后不要留空格。
说明:
方法名后紧跟左括号(。
【规则2-3-5】(向后紧跟,)、,、;向前紧跟,紧跟处不留空格。
之后要留空格。
;不是行结束符号时其后要留空格。
正例:
例子中的凵代表空格。
for(i凵=凵0;凵i凵凵MAX_BSC_NUM;凵i+)doSomething(width,凵height);【规则2-3-6】注释符与注释内容之间要用一个空格进行分隔。
正例:
/*注释内容*/注释内容反例:
/*注释内容*/注释内容1.1.4.42.4断行断行【规则2-4-1】长表达式(超过120列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。
拆分出的新行要进行适当的缩进,使排版整齐。
说明:
断行方法:
1.在逗号后断行2.在操作符前断行3.较高级别断行优于较低级别的断行对齐方法:
1.将新行与同一级别的先前行的表达式的起始端对齐。
2.条件表达式的续行在第一个条件处对齐。
3.for循环语句的续行在初始化条件语句处对齐。
4.函数调用和函数声明的续行在第一个参数处对齐。
5.赋值语句的续行应在赋值号处对齐。
6.如果上述规则导致代码排列混乱或代码左边界少于两个缩进,可用两倍缩进替代。
下面是一些断行方法调用的示例:
正例:
someMethod(longExpression1,longExpression2,longExpression3,longExpression4,longExpression5);var=someMethod1(longExpression1,someMethod2(longExpression2,longExpression3);下面是两个断行算术表达式例子,第一个是优选方法,因为断行出现在括号表达式之外,属于较高级别的断行。
正例:
longName1=longName2*(longName3+longName4-longName5)+4*longname6;/允许的断行方法反例:
longName1=longName2*(longName3+longName4-longName5)+4*longname6;/应该避免的断行方法下面是两个缩排方法的例子,第一个是传统的方式,第二个例子中如果采用传统方式缩排将导致第二行和第三行右边出现太多空白,因此,采用8个空格符替代。
/传统的缩排方法,第二行与第一行的括号对齐。
正例:
someMethod(intanArg,ObjectanotherArg,StringyetAnotherArg,ObjectandStillAnother)./你代码的位置/由8个空格符来替代与括号对齐的方法,以避免第二行、第三行出现太多的空格符正例:
privatestaticsynchronizedhorkingLongMethodName(intanArg,ObjectanotherArg,StringyetAnotherArg,ObjectandStillAnother)./你代码的位置对于if语句的行封装通常使用8空格规则,因为传统的4空格缩排方式使得有些语句容易被忽略掉,使if语句体难以理解。
例如:
反例:
/不允许使用下面的缩进方法if(condition1&condition2)|(condition3&condition4)|!
(condition5&condition6)/不好的缩进doSomethingAboutIt();/这样对齐的缩进方式很容易让阅读的人忽略掉这一行正例:
/宜采用下面的缩进方法(分成三行的情况)if(condition1&condition2)|(condition3&condition4)|!
(condition5&condition6)doSomethingAboutIt();/或使用下面的缩进方法(分成二行的情况)正例:
if(condition1&condition2)|(condition3&condition4)|!
(condition5&condition6)doSomethingAboutIt();对于三重表达式,有三种方式可以对它进行换行缩排:
正例:
/单行的情况alpha=(aLongBooleanExpression)?
beta:
gamma;/分成两行的情况,第二行的冒号与第一行的问号对齐。
alpha=(aLongBooleanExpression)?
beta:
gamma;/分成三行的情况,第二行的问号和第三行的冒号都与第一行的括号对齐alpha=(aLongBooleanExpression)?
beta:
gamma;【规则2-4-2】方法声明时,修饰符、类型与名称不允许分行书写。
正例:
publicstaticdoublecalculateArea(doublewidth,doubleheight);反例:
publicstaticdoublecalculateArea(doublewidth,doubleheight);1.1.53注释注释注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。
Java注释的方式有:
行注释:
“/注释内容”和“/*注释内容*/”两种注释形式。
文档型注释:
“/*注释内容*/”分成多行书写的形式,注释内容里包含标签。
一般类公共变量的声明采用行注释。
类、接口、构造函数、方法等的声明采用文档型注释【规则3-1】注释使用中文注释。
与doc有关的标准英文单词标签保留。
说明:
文档型注释描述了Java类(Javaclasses),接口(interfaces),构造函数(constructors)、方法(methods)和域(fields)。
每一个文档注释都包含在/*/分隔符中,每一个类(class)、接口(interface)或成员(member)都有一个注释。
这些注释应该只出现在声明(declaration)前。
标签用处用途author作者的名称类、接口说明特定某一段程序代码的作者。
每一个作者各有一个标记。
deprecated类、方法说明该类的应用程序编程接口(API)已被废弃,因此应不再使用。
exceptionnamedescription方法说明由方法发出的异常。
一个异常采用一个标记,并要给出异常的完整类名。
paramname参数名的描述方法用来说明传递给一个方法的参数,其中包括参数的类型/类和用法。
每个参数各有一个标记。
return方法返回值的描述方法若方法有返回值,对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
since类、方法例如:
sinceJDK1.1:
说明自从有JDK1.1以来,该项已存在了多长时间。
see类名类、接口、方法、字段在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
seeClassName#memberfunctionName类、接口、方法、字段在文档中生成指向特定方法的超文本链接。
可以并且应该采用完全合法的类名。
version版本号类、接口说明特定一段代码的版本信息。
【规则3-2】文件头部必须进行注释。
说明:
注释必须列出:
版权信息、文件标识、内容摘要、版本号、作者、完成日期、修改信息等。
正例:
下面是文件头部的中文注释:
/*文件名称:
题目名称*文件描述:
本类描述*版权所有:
版权所有(C)2011*公司:
东南融通系统工程(北京)有限公司*内容摘要:
/简要描述本文件的内容,包括主要模块、函数及能的说明*其他说明:
/其它内容的说明*完成日期:
/输入完成日期,例:
2011年1月25日*修改记录1:
/修改历史记录,包括修改日期、修改者及修改内容*修改日期:
*版本号:
*修改人:
*修改内容:
*修改记录2:
*version1.0*author作者姓名*/【规则3-3】公共方法前面应进行文档型注释,列出:
函数的目的/功能、输入参数、返回值等。
说明:
注释必须列出:
功能描述、输入参数、返回值等,对于成员属性的get/set操作可以不加注释。
正例:
下面是公共方法头部的注释:
/*这是对下面的方法进行文档型注释的第一行内容。
*这是对下面的方法进行文档型注释的第二行内容。
*paramname用户的名称*return返回用户的名称*/publicStringgetName(Stringname)returnname;【规则3-4】保证代码和注释的一致性。
修改代码的同时修改相应的注释,不再有用的注释要删除。
【规则3-5】注释应与其描述的代码相近,对代码的注释应放在其上方(需与其上面的代码用空行隔开)或右方(对单条语句的注释)相邻位置,不可放在下面。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
正例:
如下书写结构比较清晰/获得子系统索引subSysIndex=data.getSysIndex;/代码段1注释代码段1/*代码段2注释*/代码段2反例1:
如下例子注释与描述的代码相隔太远。
/*获得子系统索引*/subSysIndex=subSys.getSysIndex();反例2:
如下例子注释不应放在所描述的代码下面。
subSysIndex=subSys.getSysIndex();/*获得子系统索引*/反例3:
如下例子,显得代码与注释过于紧凑。
/*代码段1注释*/代码段1/*代码段2注释*/代码段2【规则3-6】注释与所描述内容进行同样的缩进。
说明:
这样可使程序排版整齐,并方便注释的阅读与理解。
正例:
如下注释结构比较清晰intdoSomething()/*代码段1注释*/代码段1/*代码段2注释*/代码段2反例:
如下例子,排版不整齐,阅读不方便;intdoSomething()/*代码段1注释*/代码段1/*代码段2注释*/代码段2建议3-1一般情况下,源程序有效注释量必须在20以上。
说明:
有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息。
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
建议3-2Java语言中,公共的属性采用单行文档注释,对于需要比较多的声明的,可进行多行注释。
正例:
对于public型变量的单行声明:
/*classVar1对classVar1的声明*/publicstaticintclassVar1;对于public型变量的多行声明:
/*classVar1对classVar1的声明第一行*对classVar1的声明第二行(继续对classVar1的声明)*/publicstaticintclassVar1;对于public型变量的多行声明:
/*classVar1对classVar1的声明第一行*对classVar1的声明第二行(继续对classVar1的声明)*/publicstaticintclassVar1;建议3-3包含在中代码块的结束处应加注释,便于阅读。
特别是多分支、多重嵌套的条件语句或循环语句。
说明:
此时注释可以用英文,方便查找对应的语句。
正例:
voiddoSomething()if()while()/endofwhile()/指明该条while语句结束/endofif()/指明是哪条语句结束/endofvoidmain()/指明函数的结束建议3-4对分支语句(条件分支、循环语句等)应编写注释。
说明:
这些语句往往是程序实现某一特殊功能的关键,对于维护人员来说,良好的注释有助于更好的理解程序,有时甚至优于看设计文档。
建议3-5通过对方法、变量等正确的命名以及合理地组织代码结构,使代码成为自注释的。
说明:
清晰准确的方法、变量的命名,可增加代码的可读性,减少不必要的注释。
建议3-6尽量避免在注释中使用缩写,特别是不常用缩写。
说明:
在使用缩写时,应对缩写进行必要的说明。
1.1.64命名规则命名规则好的命名规则能极大地增加可读性和可维护性。
同时,对于一个有上百个人共同完成的大项目来说,统一命名约定也是一项必不可少的内容。
本章对程序中的所有标识符(包括包、变量名、常量名、方法名、类名等)的命名做出约定。
对同一个项目内应使用统一的词汇表。
【规则4-1】标识符要采用英文单词或其组合,便于记忆和阅读,切忌使用汉语拼音来命名。
说明:
标识符应当直观且可以拼读,可望文知义,避免使人产生误解。
程序中的英文单词一般不要太复杂,用词应当准确。
【规则4-2】标识符只能由26个英文字母,10个数字及下划线的一个子集来组成,并严格禁止使用连续的下划线。
用户定义的标识符下划线不能出现在标识符的头尾。
说明:
这样做的目的是为了使程序易读。
因为variable_name和variable_name很难区分,下划线符号_若出现在标识符头或结尾,容易与不带下划线_的标识符混淆。
【规则4-3】标识符应当使用完整的英文描述,标识符的命名应当符合“min-length&max-information”原则,谨慎使用缩写。
说明:
对于标识符应当使用完整的英文进行描述,对于整个描述较长的,可对单词进行缩略。
较短的单词可通过去掉“元音”形成缩写,较长的单词可取单词的头几个字母形成缩写,一些单词有大家公认的缩写,常用单词的缩写必须统一。
协议中的单词的缩写与协议保持一致。
对于某个系统使用的专用缩写应该在某处做统一说明。
设计命名中应该慎用缩写命名。
如要采用,则应采用统一的缩略规则,并且在代码的相应部分统一采用缩写。
例如,采用num作为number的缩写,那么在整个代码中应该始终使用该缩写。
正例:
如下单词的缩写能够被大家认可:
temp可缩写为tmp;flag可缩写为flg;statistic可缩写为stat;increment可缩写为inc;message可缩写为msg;以下是一些常用缩写:
常用词缩写argumentargbufferbufclearclrclockclkcomparecmpconfigurationcfgcontextctxdelaydlydevicedevdisabledisdisplaydispenableenerrorerrfunctionfncthexadecimalhexinitializeinitmailboxmboxmanagermgrmaximummaxmessagemsgminimumminmultiplexmuxoperatingsystemOSparameterparampreviousprevpriorityprioreadrdreadyrdyregisterregscheduleschedsemaphoresemstackstksynchronizesynctimertmr
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编程 规范 Java
![提示](https://static.bdocx.com/images/bang_tan.gif)