Java编程规范手册

'网道Java编程规范一、目的：本规范立足于所收集到的各种Java编码标准、规范、惯例以及指导性原则，根据本公司的具体情况进行调整后制定而成，其目的是便于软件代码易于理解、维护以及重用。更为重要的事，遵循这些标准可以显著地提高软件生产率。记住：编码是具有集体性质的，其易读性、易维护性是编码优良的重要评判标准。二、原则1．尽量添加注释。2．为人编码，而不是为电脑编码。3．先做设计，然后编码。4．保持代码简单。5．从小到大编制。切忌一上手就编制大规模代码。三、基本规范1．注释在Java中，存在三种注释，分别为：l文档注释：/**………*/；l多行注释：/*………*/；l单行注释：//。这三种注释将用于不同的位置。1.1原则l尽可能进行代码注释。l力求注释简洁、清楚、易懂。 l先写注释，再写代码l除了注释代码功能外，更为重要的是注释出为什么要这样做，便于别人知道你写这段代码的目的。1.2注释规范注释类型用途例子备注文档注释（/**………*/）1.类（Class）2.接口（Interface）3.成员函数（MemberFunction）4.属性（Attribute,Field）的声明前面。/**Customer–Acustomerisanypersonororganizationthatwesellservicesandproductsto.@authorS.W.Ambler*/由于Javadoc能文档注释中的某些特定元素，故文档注释通常用于书写项目文档。多行注释（/*………*/）注释掉暂时不使用的代码。/*ThiscodewascommentedoutbyJ.T.KirkonDec9,1997becauseitwasreplacedbytheprecedingcode.Deleteitaftertwoyearsifitisstillnotapplicable....(thesourcecode)*/表明这段源代码暂时不使用。可能在以后会改变主意使用它。必须说明原因。单行注释（//）用于成员函数中说明：1.程序逻辑2.代码片断3.临时变量声明等//Applya5%discounttoallinvoices//over$1000asdefinedbytheSarek//generositycampaignstartedin//Feb.of1995.建议采用单行注释来进行代码中的说明性行为。 1.3注释的内容名称注释内容Javadoc参数参数Arguments/Parametersl参数类型l用途l使用的约束或者前提条件l尽量给出一个示例属性Fields/Attributesl属性描述l所有可能的取值或取值范围l示例l并发中可能存在的问题l可见性设置。通常属性都设置为“私有”类型，如果设置不一样，请给出原因。l@seeClassNamel@seeClassName#memberFunctionName成员函数（外部）MemberFunctionsl功能、用途以及编写该成员函数的原因l输入的参数l返回值l该函数抛出的“例外”以及抛出的条件l已知的缺陷l可见性设置l代码更改历史l示例（如何调用该成员函数）l可能的约束和前提条件l并发性策略l@paramnamedescriptionl@returndescriptionl@exceptionnamedescriptionl@deprecatedl@sincel@seeClassNamel@seeClassName#memberFunctionName 成员函数（内部）MemberFunctionsl注释局部变量l注释复杂的代码l注释控制结构，如分支、循环等，表明其控制流向及意图l注释代码功能以及缘由局部变量LocalVariablesl用途实例变量InstanceVariablesl用途类Classesl类的用途l类实例的所有取值获取值范围l已知的缺陷（通常在功能尚未完善时）l类的开发/维护历史l并发策略l@authorl@deprecatedl@sincel@seeClassNamel@seeClassName#memberFunctionNamel@version接口Interfacesl功能、用途l什么情况下适用该接口l什么情况下不适用该接口l@authorl@seeClassNamel@seeClassName#memberFunctionNamel@version 包Packagesl文件名l包名l版权信息l用途l所涉及的相关包l所包含的类l开发/维护历史2．命名2.1原则l采用有明确意义的英文单词全名（通常为名词、动词）作为描述符，但不宜于太长（一般不超过20个字符）。l每一个代码行限制在80个字符以内l采用常见的专业术语。l混合大小写形式，便于阅读。通常在定义名称时，采取名称中的每一个单词首字母大写（第一个单词首字母小写），其余字母小写的形式。l尽量不要采用缩写形式，在其缩写已经被广泛接受的情况下，采用相应的缩写方式，如URL,HTML,XML等。l虽然Java是大小写敏感的语言，但避免采用只是大小写不同的名称。如lastName和LastName等l避免使用下划线（_）以及$符号，特别是前导或后置下划线。因为这些变量经常被用作系统变量。只是在常数定义中，因采用大写形式而加入下划线以增加可读性。2.2允许的缩写名称缩写形式备注messagemsgmanagermgrdatabaseDb commandCmdimplementationimpl2.3命名规范名称命名规范例子备注参数Arguments/Parametersl该参数的英文单词l第一个英文单词首字母小写l集合参数采用复数形式firstNamelastNamecustomers属性Fields/Attributesl该属性的英文单词l第一个英文单词首字母小写l集合属性采用复数形式firstNamelastNamewarpSpeedorderItemscustomers布尔形Get函数BooleanGetterMemberFunctionslis+函数名lhas+函数名lcan+函数名isPersistent()isString()一般Get函数GetterMemberFunctionslget+函数名getFirstName()getLastName()getWarpSpeed() Set函数SetterMemberFunctionslset+函数名setFirstName()setLastName()setWarpSpeed()成员函数MemberFunctionsl尽量以一个英文动词开头l第一个英文单词首字母小写openFile()addAccount()测试函数ltest+函数名testOpenFile()主要是便于系统测试。在测试完成以后，可以搜索测试函数，将其注释调即可。局部变量LocalVariablesl第一个英文单词首字母小写，其余单词首字母大写l不要采用仅仅是大小写不同的局部变量grandTotalcustomernewAccount实例变量InstanceVariablesl采用与对象意义相关的l与普通变量命名法则相同循环计数器Loopcountersl采用惯例i,j,k,counter例外Exceptionsl采用惯例e常数Constantsl所有单词采用大写形式l单词之间用下划线分隔，以便于阅读MIN_BALANCEDEFAULT_DATE类Classesl所有单词的首字母均大写CustomerSavingsAccount 接口Interfacesl所有单词的首字母均大写ContactablePrompterSingleton为了明确意义，通常最后一个单词有后缀，如“-able”、“-ible”和“-er”等。包Packagesl包中各标识符用句点（.）分隔l由Sun公司发布的标准包是以“java”标识符开头的l局部包由小写的标识符分隔而成l全球发行的包由公司域名倒写而成java.awtpersistence.mapping.rationalinterface.screenscom.netdao.www.interface.screenscom.netdao.www.naisa.dispatcher析构器DestructorslJava本身没有析构器，但可以激活名为finalize()的函数finalize()组件Components/Widgetsl组件描述符+类型全名l第一个单词首字母小写okButtoncustomerListfileMenu构建器Constructorsl名字与类名完全相同Customer()SavingsAccount()文件名Filesl主类名+“.java”Customer.javaSavingsAccount.java四、格式1．源文件基本组织 在源文件中，建议采用以下组织。序号内容例子1包注释/**FILE:MySourceFile.javaPACKAGE:com.netdao.ymailCopyright(c)2000NetDao,Inc.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@version1.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@version1.8220Oct.2000@authorFirstNameLastName*/PublicclassMyNewClass2extendsSomeClass2{}2．辅助格式2.1空行（段落）为了增加可读性，在程序中需要加入空行，形成逻辑段落。为此原则场景例子两个空行l在每一个类或者接口申明前一个空行l在成员函数之间l方法中局部变量块申明后l逻辑块或控制块（Block）之间2.2空格与括号空格应该在以下场所适用。场景例子备注表达式中圆括号前后while(true){}参数列表中参数之间publicFootestFunc(arg1,arg2,arg3){} 操作符两端a+=c+d;while(d++=c++){}在运算符“.”两端和“++”和“--”前不要加入空格造型(cast)后面myMethod((byte)aNum,(Object)x)2.3缩进为了便于代码阅读，通常在程序中要采用缩进方式，以对齐同一级别的代码。通常每一个级别采用Tab（4个空格）方式缩进对齐。2.4换行在一个表达式太长以致于超过一行，这是需要换行。黄行需要遵循以下原则原则例子备注在表达式忠的逗号后面换行someMethod(longExpression1,longExpression2,longExpression3,longExpression4);var=someMethod1(longExpression1,someMethod2(longExpression2,longExpression3,longExpression4));在操作符前面换行longName1=longName2*(longName3+longName4–longName5)+4*longName6;但不要这样断行，尽量保持同一级别运算在同一行上longName1=longName2*(longName3+longName4–longName5)+4*longName6; 保持换行后的新行与同级别的代码对齐，如果需要很多短换行，采用与第一行所近两个Tab键位置someMethod(intargument1,Objectargument2,Stringargument3,Objectargument4){}privatestaticsynchronizedhorkingLongMethodName(intargument1,Objectargument2,Stringargument3,Objectargument4,Objectargument5){}避免出现这样的情形，而导致很多的短换行privatestaticsynchronizedhorkingLongMethodName(intargument1,Objectargument2,Stringargument3,Objectargument4,Objectargument5){}多运算符换行alpha=(aLongBooleanExpression)?beta:gamma或者alpha=(aLongBooleanExpression)?beta:gamma3．推荐修饰符顺序。修饰符时刻用于类中方法和变量的各种组合的关键字。在Java中存在一系列的修饰符。下面是推荐的修饰符顺序abstractstaticfinalnativesynchronizedinterface 其中表示public,protected和private表示transient和volatile4．其它设置名称惯例备注属性存取函数AccessorMemberFunctionsl使用属性存取函数来获取或修改所有属性l对于集合属性，添加插入和删除集合元素的成员函数一般成员函数MemberFunctionsl30秒原则。成员函数应能够让其它程序员在30秒内明白其功能，如果不能做到，说明你的代码晦涩难懂，可能不利于维护。l一行代码应完成一个功能。尽量不要把很多语句连结在一行代码上，导致可读性差。l尽可能降低成员函数的可见性。l表明各成员函数的操作顺序。属性Fields/Attributesl尽量将属性定义为私有。l尽量不要直接存取属性，应通过属性存取函数来进行属性的获取和修改l时刻记住属性的初始化工作局部变量LocalVariablesl一行定义一个局部变量，一个变量只有一种用途。l用单行注释对局部变量进行注释l在需要使用局部变量的地方进行变量定义 类Classesl近来使类具有如下结构构建器析构器finalize()public成元函数protected成员函数private成员函数private属性其它l不能直接在代码中使用数值，如100，32768等，这时应将其定义为常数来加以使用。但-1,0,1处外，它们通常作为系统特殊常数值。lswitch语句总是要有default语句。lreturn后面的返回语句不要用圆括号括起来。lif语句的代码块总是要用{}括起来，以便于阅读。4．建立公司内部的代码术语（关键词）表。形成规范。希望各位推荐个小组的术语，便于汇总。参考资料：1．JavaCodeConventions,shommel@eng.sun.com2．WritingRobustJavaCode,scott@ambysoft.com'