软件编程规范JAVA.docx
- 文档编号:20145909
- 上传时间:2023-04-25
- 格式:DOCX
- 页数:20
- 大小:25.80KB
软件编程规范JAVA.docx
《软件编程规范JAVA.docx》由会员分享,可在线阅读,更多相关《软件编程规范JAVA.docx(20页珍藏版)》请在冰豆网上搜索。
软件编程规范JAVA
1范围
本标准规定了Java语言的编程规范,主要包括基本原则、文件结构、注释、命名规则、声明、表达式与语句、类和接口等。
本标准适用于使用Java语言编码的所有软件。
2术语和定义
下列术语和定义适用于本标准。
2.1原则
编程时应该坚持的指导思想。
2.2规则
编程时必须遵守的约定。
2.3建议
编程时必须加以考虑的约定。
2.4说明
对此规则或建议的必要的解释。
2.5正例
对此规则或建议给出的正确例子。
2.6反例
对此规则或建议给出的反面例子。
3基本原则
【原则1-1】保持代码的简明清晰,避免过分的编程技巧。
说明:
简单是最美。
保持代码的简单化是软件工程化的基本要求。
不要过分追求技巧,否则会降低程序的可读性。
【原则1-2】编程时首先达到正确性,其次考虑效率。
说明:
编程首先考虑的是满足正确性、健壮性、可维护性、可移植性等质量因素,其次考虑程序的效率和资源占用。
【原则1-3】保持一致性,尽可能多的使用相同的规则。
【原则1-4】尽可能复用、修正原有的代码。
说明:
尽量选择可借用的代码,对其修改优化以达到自身要求。
【原则1-5】尽量减少同样的错误出现的次数。
说明:
事实上,我们无法做到完全消除错误,但通过不懈的努力,可以减少同样的错误出现的次数。
4文件结构
程序布局的目的是显示出程序良好的逻辑结构,提高程序的准确性、连续性、可读性、可维护性。
更重要的是,统一的程序布局和编程风格,有助于提高整个项目的开发质量,提高开发效率,降低开发成本。
同时,对于普通程序员来说,养成良好的编程习惯有助于提高自己的编程水平,提高编程效率。
因此,统一的、良好的程序布局和编程风格不仅仅是个人主观美学上的或是形式上的问题,而且涉及到产品质量,涉及到个人编程能力的提高,必须引起大家重视。
4.1基本格式
【规则2-1-1】源代码文件(.java)的布局顺序是:
包、import语句、注释、类。
正例:
packagecom.ati.**;(ati是自动化技术研究所的简写,不一定恰当)
importjava.awt.peer.CanvasPeer;
importjava.io.*;
/**
*
文件名称:
题目名称
*
文件描述:
本类描述
*
版权所有:
版权所有(C)2001-2004
*
公司:
大连理工大学自动化研究所
*
内容摘要:
//简要描述本文件的内容,包括主要模块、函数及其功能的说明
*
其他说明:
//其它内容的说明
*
完成日期:
//输入完成日期
*@version1.0
*@author作者姓名
*
修改记录1:
//修改历史记录,包括修改日期、修改者及修改内容
*
*修改日期:
*版本号:
*修改人:
*修改内容:
*
*
修改记录2:
…
*/
publicclassClassName
{
}
【规则2-1-2】程序中一行的代码和注释不能超过120列。
说明:
包括空格在内不超过120列。
【规则2-1-3】if、else、elseif、for、while、do等语句独占一行,执行语句不得紧跟其后。
不论执行语句有多少都要加{}。
说明:
这样可以防止书写失误,也易于阅读。
正例:
if(varible1 { varible1=varible2; } 或 if(varible1 varible1=varible2; } 反例: 下面的代码执行语句紧跟if的条件之后,而且没有加{},违反规则。 if(varible1 4.2空行空格 【规则2-3-1】不同逻辑程序块之间要使用空行分隔。 说明: 空行起着分隔程序段落的作用。 适当的空行可以使程序的布局更加清晰。 正例: voiddoSomething() { //[doSomething实现代码] } //空一行 voiddoOtherThing() { [doOtherThing实现代码] } 反例: voiddoSomething() { [doSomething实现代码] } voiddoOtherThing() { [doOtherThing实现代码] } //两个函数的实现是两个逻辑程序块,应该用空行加以分隔。 5注释 注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。 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)2001-2004
*
公司:
大连理工大学自动化研究所
*
内容摘要:
//简要描述本文件的内容,包括主要模块、函数及能的说明
*
其他说明:
//其它内容的说明
*
完成日期:
//输入完成日期,例:
2008年2月25日
*@version1.0
*@author作者姓名
*
修改记录1:
//修改历史记录,包括修改日期、修改者及修改内容
*
*修改日期:
*版本号:
*修改人:
*修改内容:
*
*
修改记录2:
…
*/
【规则3-3】公共方法前面应进行文档型注释,列出:
函数的目的/功能、输入参数、返回值等。
说明:
注释必须列出:
功能描述、输入参数、返回值等,对于成员属性的get/set操作可以不加注释。
正例:
下面是公共方法头部的注释:
/**
*方法描述。
*@paramid编号
*@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〗通过对方法、变量等正确的命名以及合理地组织代码结构,使代码成为自注释的。
说明:
清晰准确的方法、变量的命名,可增加代码的可读性,减少不必要的注释。
〖建议3-2〗尽量避免在注释中使用缩写,特别是不常用缩写。
说明:
在使用缩写时,应对缩写进行必要的说明。
6命名规则
好的命名规则能极大地增加可读性和可维护性。
同时,对于一个有上百个人共同完成的大项目来说,统一命名约定也是一项必不可少的内容。
本章对程序中的所有标识符(包括包、变量名、常量名、方法名、类名等)的命名做出约定。
对同一个项目内应使用统一的词汇表。
【规则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;
以下是一些常用缩写:
常用词
缩写
argument
arg
buffer
buf
clear
clr
clock
clk
compare
cmp
configuration
cfg
context
ctx
delay
dly
device
dev
disable
dis
display
disp
enable
en
error
err
function
fnct
hexadecimal
hex
initialize
init
mailbox
mbox
manager
mgr
maximum
max
message
msg
minimum
min
multiplex
mux
operatingsystem
OS
parameter
param
previous
prev
priority
prio
read
rd
ready
rdy
register
reg
schedule
sched
semaphore
sem
stack
stk
synchronize
sync
timer
tmr
trigger
trig
write
wr
【规则4-4】遵循统一的规范来书写包的声明,必须以com.ati开头。
说明:
对于包的声明,要遵循统一的命名规范来对包的声明进行说明。
大多数Java源文件的第一个非注释行是一个package语句。
包名总是小写,并且前缀是一个顶级域名(如当前的com,edu,gov,mil,net,org)或服从ISOAtandsrd3166,1981中规定的两英文字母国家标识符。
包名称的随后部分根据组织自身的命名规范变化。
这样的规范可通过指定分公司、部门、项目、机器、帐户等来确定。
正例:
packagecom.ati;
【规则4-5】类名采用大小写结合的方法,构成类名的每个单词的首字母的首字母也必须大写。
在构成类名的单词之间不用下划线。
【规则4-6】采用应用领域相关的术语来命名。
说明:
软件开发人员应注意软件用户的一些约定术语,不应当随意的创造术语,这会降低软件的易用性。
【规则4-7】程序中不要出现仅靠大小写区分的相似的标识符。
说明:
命名时应避免采用几乎相同的名称。
例如,变量名称persistentObject和persistentObjects不应当同时运用;anSqlDatabase和anSQLDatabase也不应同时使用。
【规则4-8】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
说明:
下面是一些在软件中常用的反义词组。
add/remove;begin/end;create/destroy;insert/delete;
first/last;get/set;increment/decrement;put/get;
add/delete;lock/unlock;open/close;min/max;
old/new;start/stop;next/previous;source/target;
show/hide;send/receive;source/destination;cut/paste;
up/down
【规则4-9】常量名都要使用大写字母,用下划线‘_’分割单词。
正例:
staticfinalintMIN_WIDTH=4;
staticfinalintMAX_WIDTH=999;
staticfinalintGET_THE_CPU=1;
【规则4-10】一般变量名不得取单个字符(如i、j、k等)作为变量名,局部循环变量除外。
说明:
变量,尤其是局部变量,如果用单个字符表示,很容易出错(如l误写成1),而编译时又检查不出,则有可能增加排错时间。
变量的命名应当选择精炼、意义明确的名字,才能简化程序语句,改善对程序功能的理解。
【规则4-11】变量名应该简短但意义完整,变量名的选择应该有助于记忆。
正例:
floatmyWidth;
byte[]buffer;
【规则4-12】控件命名应采用完整的英文描述符命名,名字的前缀是控件类型名。
说明:
这样容易区分一个控件的目的和它的类型,容易在一个表里找到各个控件。
正例:
btnOk
listCustomer
newFiles
【规则4-13】方法名应当能体现方法的作用,必须用小写字母开头的单词组合而成,且应当使用“动词”或者“动词+名词”(动宾词组)。
说明:
方法名力求清晰、明了,通过方法名就能够判断方法的主要功能。
多个单词组合而成的方法名中,第一个单词后面的单词采用大小写字母结合的形式(首字母大写),但专有名词不受限制。
单词间不用下划线连接。
【规则4-14】获取性方法的命名有两类,一种是判断性的操作(获取属性的状态,返回值为boolean),如判断某些控件的状态等,对于这些操作,应当是以is为方法声明的开头。
另外一种是获取返回值的操作,对一这种操作,应当以get开头。
正例:
getFirstName()
getAccountNumber()
isPersistent()
isAtEnd()
【规则4-15】属性设置性的方法命名以set开头,后紧跟属性名。
说明:
根据这个标准来命名一个类的方法,可以很容易的让人明白这个方法的基本功能。
正例:
setFirstName(StringaName)
setAccountNumber(intanAccountNumber)
setReasonableGoals(VectornewGoals)
setPersistent(booleanisPersistent)
setAtEnd(booleanisAtEnd)
【规则4-16】To型方法:
表示类型转换的方法一般用to开头。
说明:
这些方法主要用来进行类型转换。
正例:
toString()
7声明
【规则5-1】一行只声明一个变量。
正例:
intlevel;
intsize;
反例:
intlevel,size;
〖建议5-1〗变量声明应该只放在代码段的开始部分。
最好不要到使用时才声明变量。
正例:
voidmyMethod()
{
intmyInt=0;//方法块的开始
//其它语句
}
8表达式与语句
表达式是语句的一部分,它们是不可分割的。
表达式和语句虽然看起来比较简单,但使用时隐患比较多。
本章归纳了正确使用表达式和if、for、while、switch等基本语句的一些规则与建议。
【规则6-1】每一行应该只包括一个语句。
说明:
复杂的语句阅读起来难于理解,并容易隐含错误。
正例:
argv++;
反例:
argv++;argc--;
if(s4==null)s4=newString(“Joy”);
【规则6-2】在表达式中使用括号,使表达式的运算顺序更清晰。
说明:
由于将运算符的优先级与结合律熟记是比较困难的,为了防止产生歧义并提高可读性,即使不加括号时运算顺序不会改变,也应当用括号确定表达式的操作顺序。
正例:
if(((iYear%4==0)&&(iYear%100!
=0))||(iYear%400==0))
反例:
if(iYear%4==0&&iYear%100!
=0||iYear%400==0)
【规则6-3】当复合语句作为控制流程的一部分时,应该用‘{}’把所有的复合语句括起来,即使只有一句简单语句。
说明:
这样可以更方便地加入语句而不会由于忘掉加括号而引起的偶然性的错误。
正例:
intcount;
...
myMethod()
{
if(condition)
{
count=1;
}
}
〖建议6-1〗循环嵌套次数不大于3次。
9类和接口
【规则7-1】类内部的代码布局顺序:
属性、构造函数、方法。
正例:
classTest
{
publicStringname;
publicTest()
{
…;
}
publicvoidsetName(Stringname)
{
…;
}
privatevoidmethod()
{
…
}
}
〖建议7-1〗功能相关的方法放在一起。
说明:
如接口中关系较紧密的的几个方法,类属性的get和set方法,有调用关系的方法,重载的方法等有相近或相关的方法尽可能放在一起,方便阅读。
正例:
classSampleextendsObject
{
intivar1;
intivar2;
Stringname;
Sample(inti,intj)
{
ivar1=i;
ivar2=j;
}
publicvoidsetName(Stringname)
{
this.name=name;
}
publicStringgetName()
{
returnthis.name;
}
intmethod1()
{
…
method2();
}
voidmethod2()
{
…
}
}
〖建议7-2〗函数的参数个数不宜超过4个。
说明:
过多的函数参数会导致性能降低。
〖建议7-3〗保证内部类定义成private,提高类的封装性。
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编程 规范 JAVA