还剩13页未读,继续阅读
本资源只提供10页预览,全部文档请下载后查看!喜欢就下载吧,查找使用更方便
文本内容:
网道Java编程规范
一、目的本规范立足于所收集到的各种Java编码标准、规范、惯例以及指导性原则,根据本公司的具体情况进行调整后制定而成,其目的是便于软件代码易于理解、维护以及重用更为重要的事,遵循这些标准可以显著地提高软件生产率记住编码是具有集体性质的,其易读性、易维护性是编码优良的重要评判标准
二、原则1.尽量添加注释2.为人编码,而不是为电脑编码3.先做设计,然后编码4.保持代码简单5.从小到大编制切忌一上手就编制大规模代码
三、基本规范1.注释在Java中,存在三种注释,分别为文档注释/**………*/;多行注释/*………*/;单行注释//这三种注释将用于不同的位置
1.1原则尽可能进行代码注释力求注释简洁、清楚、易懂先写注释,再写代码除了注释代码功能外,更为重要的是注释出为什么要这样做,便于别人知道你写这段代码的目的
1.2注释规范注释类型用途例子备注文档注释(/**………*/)类(Class)接口(Interface)成员函数(MemberFunction)属性(AttributeField)的声明前面/**Customer–Acustomerisanypersonororganizationthatwesellservicesandproductsto.@authorS.W.Ambler*/由于Javadoc能文档注释中的某些特定元素,故文档注释通常用于书写项目文档多行注释(/*………*/)注释掉暂时不使用的代码/*ThiscodewascommentedoutbyJ.T.KirkonDec91997becauseitwasreplacedbytheprecedingcode.Deleteitaftertwoyearsifitisstillnotapplicable....thesourcecode*/表明这段源代码暂时不使用可能在以后会改变主意使用它必须说明原因单行注释(//)用于成员函数中说明程序逻辑代码片断临时变量声明等//Applya5%discounttoallinvoices//over$1000asdefinedbytheSarek//generositycampaignstartedin//Feb.of
1995.建议采用单行注释来进行代码中的说明性行为
1.3注释的内容名称注释内容Javadoc参数参数Arguments/Parameters参数类型用途使用的约束或者前提条件尽量给出一个示例属性Fields/Attributes属性描述所有可能的取值或取值范围示例并发中可能存在的问题可见性设置通常属性都设置为“私有”类型,如果设置不一样,请给出原因@seeClassName@seeClassName#memberFunctionName成员函数(外部)MemberFunctions功能、用途以及编写该成员函数的原因输入的参数返回值该函数抛出的“例外”以及抛出的条件已知的缺陷可见性设置代码更改历史示例(如何调用该成员函数)可能的约束和前提条件并发性策略@paramnamedescription@returndescription@exceptionnamedescription@deprecated@since@seeClassName@seeClassName#memberFunctionName成员函数(内部)MemberFunctions注释局部变量注释复杂的代码注释控制结构,如分支、循环等,表明其控制流向及意图注释代码功能以及缘由局部变量LocalVariables用途实例变量InstanceVariables用途类Classes类的用途类实例的所有取值获取值范围已知的缺陷(通常在功能尚未完善时)类的开发/维护历史并发策略@author@deprecated@since@seeClassName@seeClassName#memberFunctionName@version接口Interfaces功能、用途什么情况下适用该接口什么情况下不适用该接口@author@seeClassName@seeClassName#memberFunctionName@version包Packages文件名包名版权信息用途所涉及的相关包所包含的类开发/维护历史2.命名
2.1原则采用有明确意义的英文单词全名(通常为名词、动词)作为描述符,但不宜于太长(一般不超过20个字符)每一个代码行限制在80个字符以内采用常见的专业术语混合大小写形式,便于阅读通常在定义名称时,采取名称中的每一个单词首字母大写(第一个单词首字母小写),其余字母小写的形式尽量不要采用缩写形式,在其缩写已经被广泛接受的情况下,采用相应的缩写方式,如URLHTMLXML等虽然Java是大小写敏感的语言,但避免采用只是大小写不同的名称如lastName和LastName等避免使用下划线(_)以及$符号,特别是前导或后置下划线因为这些变量经常被用作系统变量只是在常数定义中,因采用大写形式而加入下划线以增加可读性
2.2允许的缩写名称缩写形式备注messagemsgmanagermgrdatabaseDbcommandCmdimplementationimpl
2.3命名规范名称命名规范例子备注参数Arguments/Parameters该参数的英文单词第一个英文单词首字母小写集合参数采用复数形式firstNamelastNamecustomers属性Fields/Attributes该属性的英文单词第一个英文单词首字母小写集合属性采用复数形式firstNamelastNamewarpSpeedorderItemscustomers布尔形Get函数BooleanGetterMemberFunctionsis+函数名has+函数名can+函数名isPersistentisString一般Get函数GetterMemberFunctionsget+函数名getFirstNamegetLastNamegetWarpSpeedSet函数SetterMemberFunctionsset+函数名setFirstNamesetLastNamesetWarpSpeed成员函数MemberFunctions尽量以一个英文动词开头第一个英文单词首字母小写openFileaddAccount测试函数test+函数名testOpenFile主要是便于系统测试在测试完成以后,可以搜索测试函数,将其注释调即可局部变量LocalVariables第一个英文单词首字母小写,其余单词首字母大写不要采用仅仅是大小写不同的局部变量grandTotalcustomernewAccount实例变量InstanceVariables采用与对象意义相关的与普通变量命名法则相同循环计数器Loopcounters采用惯例ijkcounter例外Exceptions采用惯例e常数Constants所有单词采用大写形式单词之间用下划线分隔,以便于阅读MIN_BALANCEDEFAULT_DATE类Classes所有单词的首字母均大写CustomerSavingsAccount接口Interfaces所有单词的首字母均大写ContactablePrompterSingleton为了明确意义,通常最后一个单词有后缀,如“-able”、“-ible”和“-er”等包Packages包中各标识符用句点(.)分隔由Sun公司发布的标准包是以“java”标识符开头的局部包由小写的标识符分隔而成全球发行的包由公司域名倒写而成java.awtpersistence.mapping.rationalinterface.screenscom.netdao.www.interface.screenscom.netdao.www.naisa.dispatcher析构器DestructorsJava本身没有析构器,但可以激活名为finalize的函数finalize组件Components/Widgets组件描述符+类型全名第一个单词首字母小写okButtoncustomerListfileMenu构建器Constructors名字与类名完全相同CustomerSavingsAccount文件名Files主类名+“.java”Customer.javaSavingsAccount.java
四、格式1.源文件基本组织在源文件中,建议采用以下组织序号内容例子1包注释/**FILE:MySourceFile.javaPACKAGE:com.netdao.ymailCopyrightc2000NetDaoInc.AllRightsReservedCommentsHistory:2000/10/20:DeveloperNameChangesomecode2000/09/12DeveloperNameAddMemberFunction2000/09/01DeveloperNameCreatethisfile*/2包名packagecom.netdao.ymail;3引入Java公共包importjava.util.Calendar;4引入第三方包importcom.weblogic.*;5引入自己的项目包importcom.netdao.ymail.*;6类注释/**ClassMyNewClass1Descriptiongoeshere@version
1.8220Oct.2000@authorFirstNameLastName*/7类声明PublicclassMyNewClass1extendsSomeClass1{}8变量声明(含注释)publicprotectedpackagelevelvariableprivate/**classVar1的文档注释*/publicintclassVar1;9实例变量申明(含注释)publicprotectedpackagelevelvariableprivate/**instanceVar1的文档注释*/publicObjectinstanceVar1;10构建器/**MyNewClass的文档注释*/publicMyNewClass{//implementation}11方法/**doSomething1方法的文档注释*/publicvoiddoSomething1{//implementation}/**doSomething2方法的文档注释@paramsomeParamdescription@returndescription@exceptionsomeExecptiondescription*/publicvoiddoSomething2{//implementation}12其它类申明/**ClassMyNewClass2Descriptiongoeshere@version
1.8220Oct.2000@authorFirstNameLastName*/PublicclassMyNewClass2extendsSomeClass2{}2.辅助格式
2.1空行(段落)为了增加可读性,在程序中需要加入空行,形成逻辑段落为此原则场景例子两个空行在每一个类或者接口申明前一个空行在成员函数之间方法中局部变量块申明后逻辑块或控制块(Block)之间
2.2空格与括号空格应该在以下场所适用场景例子备注表达式中圆括号前后whiletrue{}参数列表中参数之间publicFootestFuncarg1arg2arg3{}操作符两端a+=c+d;whiled++=c++{}在运算符“.”两端和“++”和“--”前不要加入空格造型cast后面myMethodbyteaNumObjectx
2.3缩进为了便于代码阅读,通常在程序中要采用缩进方式,以对齐同一级别的代码通常每一个级别采用Tab(4个空格)方式缩进对齐
2.4换行在一个表达式太长以致于超过一行,这是需要换行黄行需要遵循以下原则原则例子备注在表达式忠的逗号后面换行someMethodlongExpression1longExpression2longExpression3longExpression4;var=someMethod1longExpression1someMethod2longExpression2longExpression3longExpression4;在操作符前面换行longName1=longName2*longName3+longName4–longName5+4*longName6;但不要这样断行,尽量保持同一级别运算在同一行上longName1=longName2*longName3+longName4–longName5+4*longName6;保持换行后的新行与同级别的代码对齐,如果需要很多短换行,采用与第一行所近两个Tab键位置someMethodintargument1Objectargument2Stringargument3Objectargument4{}privatestaticsynchronizedhorkingLongMethodNameintargument1Objectargument2Stringargument3Objectargument4Objectargument5{}避免出现这样的情形,而导致很多的短换行privatestaticsynchronizedhorkingLongMethodNameintargument1Objectargument2Stringargument3Objectargument4Objectargument5{}多运算符换行alpha=aLongBooleanExpressionbeta:gamma或者alpha=aLongBooleanExpressionbeta:gamma3.推荐修饰符顺序修饰符时刻用于类中方法和变量的各种组合的关键字在Java中存在一系列的修饰符下面是推荐的修饰符顺序accessabstractstaticfinalunusualnativesynchronizedinterface其中access表示publicprotected和privateunusual表示transient和volatile4.其它设置名称惯例备注属性存取函数AccessorMemberFunctions使用属性存取函数来获取或修改所有属性对于集合属性,添加插入和删除集合元素的成员函数一般成员函数MemberFunctions30秒原则成员函数应能够让其它程序员在30秒内明白其功能,如果不能做到,说明你的代码晦涩难懂,可能不利于维护一行代码应完成一个功能尽量不要把很多语句连结在一行代码上,导致可读性差尽可能降低成员函数的可见性表明各成员函数的操作顺序属性Fields/Attributes尽量将属性定义为私有尽量不要直接存取属性,应通过属性存取函数来进行属性的获取和修改时刻记住属性的初始化工作局部变量LocalVariables一行定义一个局部变量,一个变量只有一种用途用单行注释对局部变量进行注释在需要使用局部变量的地方进行变量定义类Classes近来使类具有如下结构构建器析构器finalizepublic成元函数protected成员函数private成员函数private属性其它不能直接在代码中使用数值,如100,32768等,这时应将其定义为常数来加以使用但-101处外,它们通常作为系统特殊常数值switch语句总是要有default语句return后面的返回语句不要用圆括号括起来if语句的代码块总是要用{}括起来,以便于阅读4.建立公司内部的代码术语(关键词)表形成规范希望各位推荐个小组的术语,便于汇总参考资料1.JavaCodeConventionsshommel@eng.sun.com2.WritingRobustJavaCodescott@ambysoft.com。