Java编程规范.docx
- 文档编号:12014010
- 上传时间:2023-04-16
- 格式:DOCX
- 页数:18
- 大小:25.62KB
Java编程规范.docx
《Java编程规范.docx》由会员分享,可在线阅读,更多相关《Java编程规范.docx(18页珍藏版)》请在冰豆网上搜索。
Java编程规范
Java编程规范
嵌入式产品部
中科软科技股份限公司
[作者:
Jeff]
版本1.0[草稿]
完成日期:
2002-1-17
郑重声明
本文中的绝大多数内容都摘自“JavaCodingStandard.pdf”,其中我仅仅做了少量的修改和说明,基本就是抄袭。
详细信息请参见原文。
说法不对的地方,请及时反馈给Jeff。
1.基础
1.1如何定义一个好的名字
●使用完整的语言来描述变量/属性/类/…,不要采用简写。
例如变量CustomerName,不要使用CustNm。
(如果使用简写,则采用统一的标准)
●采用所涉及的领域中的专用术语,例如针对习惯,将客户都称为Customer,或是Client,不要混合两者使用。
●混合使用大小写,使名称更容易被他人看懂。
●尽量少使用简写,如果使用,则要保证一致性,例如,对于number,可以使用nbr、num或是no,但不管使用哪一个,都要保证编程中的一致性,并将自己的简写规范写入自己的简写文档。
●尽量不要出现超过15个字符的名称。
例如对于PhysicalOrVirtualProductOrService,可以用Offering代替。
●避免名称相似或是仅仅在大小写上有区别。
1.2良好的文档
●添加适当的注释,使你的代码能够很容易被人看懂。
●如果你的代码不值得注释,那么这些代码也不值得运行。
●避免使用太多的装饰用注释,例如使用太多的*号来装饰你的注释。
●保持注释的简洁,只要保证能说明你的代码就行,不必象写书一样。
●在编写代码之前编写注释。
这种方法一是能保证你写注释,另一个优点是可以帮助你整理思路。
●注释中要能解释为什么这么做,而不仅仅是做了什么。
例如对于下面的代码,就需要解释为什么使用魔术数字1000和0.95。
if(grandTotal>=1000.00)
{
grandTotal=grandTotal*0.95;
}
1.3Java的注释
Java的注释有三种类型
注释类型
用法
例子
文档(用于Javadoc)注释
紧接在接口、类、成员函数之前的注释,便于javadoc处理,详细信息参见javadoc文档(参见下面提到的题头)
/**
Customer–客户指的是我们向他销售服务和产品的人或组织
@authorJeff.Liu
*/
C类型
多用于主要注释多行,这种注释的用途主要表明作者的意图,或是在调试时临时注释
/*
这段代码是由Jeff.Liu在2002年1月10日注释的,原因是这段代码已被上面的代码替代。
如果两年后仍然不需要这些代码,请到时将它删除。
...(thesourcecode)
*/
单行
多用于为成员函数编写业务逻辑文档或是声明临时变量。
//从1995年开始,对所有超过1000美元的
//发票提供5%的折扣
本规范规定:
对于所有的接口、类、成员函数必须提供文档注释,使用C类型的注释来标注旧的代码和调试时使用,利用单行注释来注释业务逻辑以及对临时变量的说明。
1.3.1javadoc概要
以后再说吧
2.成员函数标准
成员函数的相关注释
2.1成员函数命名规范
成员函数的命名采用完整的英文描述方式来编写,其中第一个英文单词的首字母采用小写,之后的单词的首字母大写。
举例:
openAccount()
printMailingLabel()
save()
delete()
2.1.1Getter函数的命名
Getter函数用于返回属性的值。
此类函数的命名规范是在属性名称的前面添加get前缀。
例如:
getFirstName()
getAccountNumber()
getLostEh()
2.1.2Setter函数的命名
Setter函数用于设置属性的值,此类函数的命名规范是在属性名称的前面添加set前缀。
举例:
setFirstName(StringaName)
setAccountNumber(intanAccountNumber)
setReasonableGoals(VectornewGoals)
setPersistent(booleanisPersistent)
setAtEnd(booleanisAtEnd)
2.1.3构建函数
构建函数必须与类名完全相同,这是Sun定义的规范!
例如Customer类的构建函数为Customer()。
2.2成员函数的可视性
一个好的设计要尽量减少类之间的耦合,因此,对于成员函数的可视性必须尽量采用严格的策略,不必public的,采用protected,不必protected的,采用private。
可视性
说明
适用条件
public
public的成员可以被其它所有的对象或类调用
当成员函数要被类的继承层次之外的对象或类访问时
protected
protected的成员函数只能被这个类的子类访问
当成员函数仅仅在类的继承层次上需要,对外部不需要时。
private
private的成员函数只能被这个类中的成员函数访问,它的子类也不能访问
当成员函数仅仅在类内部使用时。
如果没有指明可视性,则采用缺省的或包(package)内可视性。
这个成员函数对本包内的所有类公开(public),但对于包外的类保持private。
仅当您需要在一个包内实现一个内聚性很强的业务逻辑时,考虑使用这种方式。
2.3成员函数的题头
在每个成员函数代码的上面都应该编写成员函数文档,其中描述的是对这个成员函数的说明。
题头中的内容包括如下几个方面:
●*明确这个成员函数的用途,描述这个成员函数使用时的上下文环境。
●*解释成员函数的参数的含义,以及如何使用这些参数。
javadoc中的@param标记就是用于标记参数。
●*成员函数的返回值。
利用javadoc中的@return标记。
●已知的bug。
表明成员函数的弱点。
●成员函数抛出的例外。
便于其它程序员在他们的代码中捕捉(catch)。
利用javadoc的@exception标记。
●成员函数如何影响对象。
例如对于银行帐户对象的withdraw()函数,应当表明它更改了帐户余额。
●包括历史代码的更改。
如果对成员函数进行了大的变化,则要表明更改了什么内容(在我们开始使用版本控制软件后,可以不包括这一内容)。
●如果成员函数的调用方式不太直观,或是有特别注意的地方,则利用例子进行说明。
●所有的并发性问题。
如果您在编码中出现了并发性问题、使用了同步等方式,则要对本函数中的所有并发性问题进行说明。
以上内容仅供参考,并不一定适合所有的成员函数,可根据具体情况确定,原则就是尽量让别人能看懂你的代码,并易于维护和改善。
但是其中前三项必须注明,除非没有参数,或是没有返回值。
2.4内部注释
除了函数题头外,还要在成员函数的内部使用注释,这在前面的基础部分中已经说明了各种注释方式用途,这里强调指出:
由于C类型的注释与题头的注释十分相似,因此,除了用于注释掉不再使用的代码以及简短表述编写者的意图之外,尽量少使用。
对于业务逻辑的注释,统一采用单行注释。
在函数体的内部,您应当注释的内容是:
●控制结构。
描述每一个控制结构所完成的内容。
描述的详细程度要达到:
以后阅读代码时无需阅读所有的代码,只需阅读这一结构之前的注释即可了解它所完成的功能。
●对于关键代码段,尤其是关键性的算法以及带有数字(魔术数字)的地方,除了需要注释说明完成的内容之外,还要标明为什么这样做。
●局部变量。
后面还有详细的说明变量的内容。
这里仅仅指出:
成员函数内部定义的每个局部变量,都需要在这个变量的后面,用单行注释说明它的用途。
●对于困难或复杂的代码,会影响别人的阅读,要求必须有更为详细的文档说明。
●如果在代码段中的有严格先后执行顺序的语句,尤其是多个成员函数的调用有先后顺序时,必须加以说明。
建议:
对于“}”号,在它的后面标注结束的内容,例如//endif,//endfor,//endswitch,这样程序的可读性会更好。
2.5编写干净的代码的技巧
1.在您的代码中加注释(文档化)
2.将您的代码分段,并使用缩进
要求:
对于{}位置,采用下例子所示的风格,即{与起始语句位于一行。
publicSearchResults(){
status=newStatus();
results=newSearchResultBean[0];
}
3.对于很长的语句,进行断行处理,折下去的一行要使用缩减处理,以表明与上面一行是一个整体,例如
BankAccountnewPersonalAccount=AccountFactory
createBankAccountFor(currentCustomer,startDate,
initialDeposit,branch);
4.使用空白,例如
不好的代码:
counter=1;
grandTotal=invoice.total()+getAmountDue();
grandTotal=Discounter.discount(grandTotal,this);
好的代码:
counter=1;
grandTotal=invoice.total()+getAmountDue();
grandTotal=Discounter.discount(grandTotal,this);
5.遵循30秒规则
这是一个建议性原则,就是尽量保证你的函数能让别人在30秒内看懂。
呵呵,这个规则有时有些难度,尽力吧。
6.编写简短、单行的语句
这是一个建议性规则。
就是尽量在一行内完成任务,不要将代码的长度超过可视屏幕,如果你发现你的代码太长,那你基本上需要重新考虑算法。
3.属性相关标准
3.1属性的命名
在命名时采用完整的描述(无论英文,还是拼音)。
对于arrays或vectors,应当在名称中就标记为复数。
第一个单词的首字母小写,其后的单词的首字母大写。
如果第一个单词是一个缩写(例如sql),则整个缩写都采用小写,不要有的使用小写,有的使用大写。
举例:
firstName
zipCode
unitPrice
discountRate
orderItems
sqlDatabase
3.1.1命名图形控件
对于界面图形控件的命名,要在名称的后面标注完整的控件的名称。
举例:
okButton
customerList
fileMenu
newFileMenuItem
3.1.2常量的命名
Java中常量的声明是在变量的定义的前面加上staticfinal修饰符号。
所有的单词都采用大写,单词之间用下划线间隔。
举例:
MINIMUM_BALANCE
MAX_VALUE
DEFAULT_START_DATE
3.1.3集合类型的命名
对于集合类型的变量,要用复数表示。
举例:
customers
orderItems
3.2属性的可视性
可视性
说明
合理使用
public
public属性可以倍其它所有对象或类访问
尽量不要使用public
protected
protected属性可以这个类以及它的子类的成员函数访问
尽量不要使用protected
private
private属性只可以被自己所在的类中的成员函数访问,子类也不能访问
尽量将所有的属性设置为private,并通过getter和setter成员函数(访问函数)来读取和设置各个属性。
在实体EJB中,如果属性不是永久性的(即不会存储到数据库中),您应当将这些属性标记为transient。
3.3属性的注释
每个属性都应当书写足够的注释,以便其它程序员方便地了解。
为保证提供有效的注释,您应当编写如下内容:
1.属性的说明。
您需要对属性进行说明,以便其它人可以了解如何使用它。
2.举例。
对于与复杂的业务逻辑相关的属性,您需要提供多个举例值。
3.并发问题。
如果您在编程中利用了Java的并发编程功能,您应当提供完整的文档来说明。
3.4使用访问函数
访问函数主要用于更新和获取某个属性的值。
主要有两种:
setter和getter。
setter函数用于更改变量的值,getter用于获取变量的值。
尽管访问函数增加了代码的任务量,但这种方式封装类中的实现细节,并且更易于维护。
因此,除非特别需要,都希望利用这种方式。
注意:
如果您采用了setter和getter函数来访问变量,虽然您的确可以在其它成员函数中直接访问这个变量,但不要这么使用,也要通过访问函数来操作变量。
3.4.1访问函数的命名
getter成员函数的命名方式是‘get’+属性名称,但有一个例外就是:
对于boolean型的属性,getter的命名方式是‘is’+属性名称。
setter成员函数的命名方式:
‘set’+属性名称。
注意:
其中属性的名称的首字母要大写。
举例:
属性
类型
getter函数名
setter函数名
firstName
string
getFirstName()
setFirstName()
address
AddressObject
getAddress()
setAddress()
persistent
boolean
isPersistent()
setPersistent()
orderItems
ArrayofOrderItemobjects
getOrderItems()
setOrderItems()
对集合类型的变量的访问函数的特别说明:
集合类型(例如array和vector)等,除了set和get函数之外,还可以补充“插入”,“添加”和“删除”三个访问函数。
成员函数的类型
命名规范
举例
集合类型的getter函数
getCollection()
getOrderItems()
集合类型的setter函数
setCollection()
setOrderItems()
向集合中插入对象
insertObject()
insertOderItem()
从集合中删除对象
deleteObject()
deleteOderItem()
创建并添加一个新的对象
newObject()
newOrderItem()
3.4.2使用访问函数的一些好处
1.通过一个入口来更新属性的值
2.便于控制如何访问属性的值,例如可以控制谁可以访问某个属性
3.可以用来初始化属性的值
4.减少了子类和父类之间的耦合
5.当更新一个属性时,可以方便地考虑业务,例如可能会同时更新其它属性
6.简化了并发性问题。
setter函数就是控制并发性的很好的地方
3.5别忘记初始化Static属性
如果某个属性是静态的,别忘了在定义时就为它赋值。
4.局部变量标准
4.1局部变量的命名
局部变量的命名方式基本与属性的命名方式相同。
但是为了方便,有些特殊类型的局部变量的命名方式有所不同:
●流
●循环变量
●例外
4.1.1流的命名
对于在一个成员函数内打开、使用并关闭的输入或输出流,常用的命名方式是使用in和out来作为这些流的名字。
如果一个流同时作为输入和输出,则可以采用inOut的名称。
这种方式也是Sun建议的方式。
但我们建议,利用inputStream、outputStream和ioStream这三个变量来代替上面的三个变量。
4.1.2循环变量的命名
我们推荐仍然沿用大家经常采用的i、j和k等单字母命名方式,但也不排斥采用类似loopCounter等的命名方式。
4.1.3例外对象的命名
因为在Java代码中常常使用字母e来作为例外对象,因此我们也使用e作为通用的例外命名方式。
4.2局部变量的声明和注释
局部变量的声明和注释遵循如下规范:
1.每行仅声明一个变量。
2.在变量声明的行尾,用//注释方式表明变量的用途。
3.尽量将一个局部变量仅用于一个用途。
以便其它程序员更容易理解您的代码。
5.成员函数的参数标准
5.1参数的命名
参数的命名与局部变量的命名方式相同。
举例:
customer
inventoryItem
inputStream
e
5.2参数注释
对于成员函数的参数的注释,应通过javadoc@param标记,放置在成员函数的题头注释中。
注释中应当描述:
1.参数的用途。
2.对参数的限制。
例如正数,或字符串的长度不超过5个。
3.在参数的调用方式不是很明显的情况下,应当提供参数值的举例。
简单例子:
/**
*ProcessthespecifiedHTTPrequest,andcreatethecorrespondingHTTP
*response(orforwardtoanotherwebcomponentthatwillcreateit).
*ReturnanActionForward
instancedescribingwhereandhow
*controlshouldbeforwarded,ornull
iftheresponsehas
*alreadybeencompleted.
*
*@parammappingTheActionMappingusedtoselectthisinstance
*@paramactionFormTheoptionalActionFormbeanforthisrequest(ifany)
*@paramrequestTheHTTPrequestweareprocessing
*@paramresponseTheHTTPresponsewearecreating
*
*@exceptionIOExceptionifaninput/outputerroroccurs
*@exceptionServletExceptionifaservletexceptionoccurs
*/
6.类、接口、包的标准
6.1类标准
6.1.1类的可视性
类的可视性有两种:
public和package(缺省)。
public的可视性是通过关键字public来指定,package的可视性不用指明,是缺省值。
public的类,其它类中都可以使用,但package的类只能在同一个包中的类中使用。
原则上是尽量使用package,仅对于对外提供统一接口的类使用public的可视性。
6.1.2类的命名
类的命名尽量采用完整的描述(能表述类的含义),第一个字母要大写。
举例:
Customer
Order
OrderItem
FileStream
6.1.3类的注释
在类的定义之前(紧挨着类的定义)应当提供如下内容的注释:
1.类的用途。
表述类的用途等相关信息,对于类中的一些限制条件,也应加以描述。
2.已知的bug。
如果类的设计中有明显的缺陷,应当指明。
另外,还要说明为什么没有解决这个bug。
注意,如果bug是针对某个成员函数的,则应当将这个bug放到成员函数之前的说明中。
3.这个类的开发/维护历史。
说明修改者、日期以并概要描述所做的改动。
4.并发策略。
每个实现Runnable的类都要完整描述它的并发策略。
通用的解决并发的策略有:
Synchronizedobjects,balkingobjects,guardedobjects,versionedobjects,concurrencypolicycontrollers和acceptors。
(呵呵,Jeff对这些策略了解得也不多,大家查资料吧,这里算是抛砖引玉)
简单例子:
/**
*AnActionForwardrepresentsadestinationtowhichthe
*controllerservlet,ActionServlet
,mightbedirectedto
*performaRequestDispatcher.forward()
or
*HttpServletResponse.sendRedirect()
to,asaresultof
*processingactivitiesofanAction
class.Instancesofthis
*classmaybecreateddynamicallyasnecessary,orconfiguredinassociation
*withanActionMapping
instancefornamedlookupofpotentially
*multipledestinationsforaparticularmappinginstance.
*
*AnActionForward
hasthefollowingminimalsetofproperties.
*Additionalpropertiescanbeprovidedasneededbysubclassses.
*
- name-Logicalnamebywhichthisinstancemaybe
*lookedupinrelationshiptoaparticular
ActionMapping
.*
- path-Context-relativeURItowhichcontrolshould
*beforwarded,oranabsoluteorrelativeURItowhichcontrolshould
*beredirected.
*
- redirect-Setto
true
ifthecontroller*servletshouldcall
HttpServletResponse.sendRedirect()
*ontheassociatedpath;otherwise
false
.[false]*
*
*
*@authorCraigR.McClanahan
*@version$Revision:
1.4$$Date:
2001/02/2100:
35:
44$
*/
6.1
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Java 编程 规范