还剩13页未读,继续阅读
本资源只提供10页预览,全部文档请下载后查看!喜欢就下载吧,查找使用更方便
文本内容:
J__A编程语言的代码惯例
1、介绍1.1___要有代码惯例代码惯例之所以重要有以下几点原因软件寿命价值的80%是维护几乎没有软件在整个使用过程中都有由原__维护代码惯例增加了软件包的可读性,使工程师们能更快、更完整地理解新软件如果你想把你的原始代码变成产品,你需要确认它是否和你生产的其它产品一样有好的包装1.2确认这个文件在SUN公司的J__A语言说明书中反映了J__A语言编码标准这方面规定主要来自PeterKingPatrickNaughtonJonniKanervaandScottHommel.关于这个文档的改写、修改或再分配的问题,请看版权公告对于这个文档的建议请发贴自alans@eng.sun.com2------文件名这一节列举了常用的文件后缀与名称2.1文件后缀J__A使用以下后缀文件种类后缀J__Asour__.j__aJ__Abytecode.class2.2普通文档名称通常用的文档名称文档名称使用GNU__kefile__kefile最恰当的名字我们使用gnu__ke制造我们的软件Readme概括特定目录内容的文档的最恰当名称
3.文件的组织结构一个文件应当由多个被分隔的段组成,并由空行和可选择注释来识别超过2000行的文件由于冗长而应当避免J__a程序的正确格式可参看第19页的范例“J__a源文件范例”3.1J__a源文件每一个J__a源文件包含一个单一的公共类或界面当私有类或界面与一个公共类发生__时,你可以将它们以一个公共类放入同一个源文件公共类应当是文件中的第一类或界面J__a源文件有如下次序起始注释(参看第4页“起始注释”)组件和导入语句类和界面声明(参看第4页“类和界面声明”)3.1.1起始注释所有源文件应当以C格式注释开始,并列出类名,版本信息,时间和版权说明/**类名**版本信息**时间**版权说明*/3.1.2组件和导入语句对于大部分J__a源文件而言,第一个无注释行是组件语句之后,紧跟着是导入语句举例如下组件j__a.awt;导入j__a.awt.peer.CanvasPeer注释对于唯一的组件名,第一部分总是小写的ASCII码格式的文本文件,并且是最高级别的域名之一目前可用comedugovmilnet或ISO3166标准
(1981)中规定的用于识别国家的英文两个字母的模式3.1.3类和界面声明下表按出现的先后顺序描述了一个类或界面说明的各部分参见第19页“j__a源文件范例”中一个包含注释的示例类/界面声明的各部分注释1类/界面文档注释/**…*/参看第9页“文挡注释”中注释的具体内容2类或界面语句3类/界面补充注释(/*…*/),如果必要的话这一注释应包含任一类宽或界面宽度的信息,它不适合于类/界面文档注释4类(静态的)变量首先是公共类变量,其次是保护类,然后是组件级(无访问修改权),最后是私有类5实例变量首先是公共类,其次是保护类,然后是组建级(无访问修改权),最后是私有类6构成7过程这些过程应当以功能而非作用域和可访问性来分组举例说明,一个私有类变量过程可在两个公共实例过程中其目的是使读和理解代码更为容易
4、缩进格式四个空格作为一个缩进单位确切的缩进格式结构(空格符与制表符)未被规范表格的设置必须在每8个空格后(而非4个)4.1行的长度由于难于被大多数终端和工具进行处理,应当避免一行超过80个字符注释在文档中所列举的范例其行的长度应稍短些,一般不超过70个字符4.2绕回行当表达式一行无法写完时,使用以下一般规则进行中断在逗号后中断在一个运算符前中断优先选择高级中断指令新行起始表达式的位置应与旧行表达式的位置对齐如果上述规则导致代码混乱或编码时顶到了右边界,以8个空格代替以下是几个中断程序的调用范例someMethodlongExpression1longExpression2longExpression3longExpression4longExpression5;var=someMethod1longExpression1someMethod2longExpression2longExpression3;以下是两个关于中断算术表达式的例子第一个例子由于中断发生在插入表达式以外,因而选择了高级中断指令longName1=longName2*longName3+longName4–longName5+4*longname6;//PREFERlongName1=longName2*longName3+longName4longName5+4*longname6;//__OID以下是两个关于缩进程序的说明第一个例子是常规情况第二个例子如果采用常规缩进方式,第二和第三行在换行时必然顶至最右,取而代之应空8格//常规的缩进方式someMethodintanArgO__ectanotherArgStringyetAnotherArgO__ectandStillAnother//缩8个空格以避免更深的锁进privatestaticsynchronizedhorkingLongMethodNameintanArgO__ectanotherArgStringyetAnotherArgO__ectandStillAnother由于常规的4空格缩进方式使得体看上去过于复杂,对于语句的绕回行我们一般采用8空格缩进方式举例如下//不要使用这种缩进方式ifcondition1condition2condition3condition4!condition5condition6//BADWRAPSdoSomethingAboutIt;//__KETHISLINEEASYTOMISS//取而带之使用这种缩进方式ifcondition1condition2condition3condition4!condition5condition6doSomethingAboutIt;//或使用这种方式ifcondition1condition2condition3condition4!condition5condition6doSomethingAboutIt;以下有三种可行的方式来格式化三元表达式alpha=aLongBooleanExpressionbeta:gam__;alpha=aLongbooleanExpressionbeta:gam__;alpha=aLongBooleanExpressionbeta:gam__;5注释J__A程序可以有二种类型的注释执行注解和文件注释执行注释是建立在C++之上的,以/*…*/为分隔符的注释;文件注释(即通常所说的doccomment)是一种纯J__A注释,以/**…*/为分隔符Doccomment文件注释能够通过J__ADOCA工具被摘录成HEML文件执行注释是指为代码注解释,或为特别执行注解释Doc注释旨在从一个自由执行的程序描述代码的规范,对于软件__者来说,手边不再需要源代码就可以阅读注释通常用于对代码做总的描述,同时提供附加的信息,这从代码本身来看是不容易得到的其包含的信息只与阅读、理解该程序有关,例如一个相应组件如何被建立的信息或驻足在何地址录下的信息都将被包含在一个注解中对于重要的、非显而易见的设计决定的讨论是适当的,但是应该避免重复信息在代码中出现而对于多余注释,则很容易成为过时的总的说来,应当避免把过时的注释做为编码的进展注意经常出现的注释有时反映编码质量的低下当你觉得不得不添加注释时,建议你最好重新编写,使得编码更清晰注释不能以星号或是其它字符为标识被附在一个大的逻辑单元内注释也不能包括特殊字符例如form-feed和backspa__
5.1执行注释的格式程序可以有四种注释风格块、单行、跟踪和行尾
5.
1.1块注释块注释用于提供文件的描述、方法、数据结构和运算法则块注释用于每个文件的开始和方法之前也可以用在其他地方,比如用在方法中在一个函数或方法中的块注释,应和他们描述的代码排列到同一级别上块注释应设置在一个空行的开始/**Hereisablockcomment.*/块注释以/*开始,并且单独__一行,缩进一格作为块注释的开始,这已经是约定俗成的,不需要另外重新定义格式例如/*-*Hereisablockcommentwithsomeveryspecial*for__ttingthatIwantindent1toignore.**one*two*three*/Note:Ifyoudontuseindent1youdonth__etouse/*-inyourcodeor__keanyothercon__ssionstothepossibilitythatsomeoneelsemightrunindent1onyourcode.
5.
1.2单行注释简短的注释可以出现在单行上,和其描述的代码在同一级别上单行注释应遵循块注释的格式单行注释应单起一行例如ifcondition{/*Handlethecondition.*/...}
5.
1.3跟踪注释简短的注释可以和其所描述的代码放到同一行上但应和代码保持足够远的空间如果不只一个简短的注释出现在大块的代码段中,它们应有同样的tab设置例如ifa==2{returnTRUE;/*specialcase*/}else{returnisPrimea;/*worksonlyforodda*/}
5.
1.4行尾注释//注释界定符能注释一整行或行的一部分,它不应该用在连续的多行文本注释中然而,它可以用在连续的多行代码段中例如iffoo1{//Doadouble-flip....}else{returnfalse;//Explainwhyhere.}//ifbar1{//////Doatriple-flip.//...//}//else{//returnfalse;//}
5.2文件注释文件注释描述J__a类、界面、容器、方法和域,每一个文件注释都放在注释界定符/**...*/之间注释应在声明之前/***TheExampleclassprovides...*/publicclassExample{...注意顶级类和界面不缩进,子类和界面则要缩进类和界面的第一行文件注释不缩进,后面的注释行有有一个空格的缩进子类,包括容器,有4个空格和五个空格的缩进如果你需要给出关于类、界面变量或方法的信息,这些信息以文件的方式给出是不适当的,那麽你可以直接的在声明之后使用执行块注释或单行注释例如,类执行的细节信息应放进执行块注释中,并跟在类语句之后,而不是放在类的文件注释中文件注释不应该放到方法或容器的定义块中,因为J__a将文件注释和第一个注释之后的声明发生__
6、声明
6.1每一行的数量每一行中都应有相应的注释,换句话说intlevel;//indentationlevelintsize;//sizeoftable这种形式是首选的,而不是intlevelsize;不要将不同类型的放入同一行中,例如intfoofooarray[];//WRONG!注意上面的例子中在类型和标识之间有一个空格,另一个可接受的方法是用tab,例如intlevel;//indentationlevelintsize;//sizeoftableO__ectcurrentEntry;//currentlyselectedtableentry
6.2初始化被声明的局部变量,应设法将其初始化
6.3布置声明应放在块的开始不要一直到用到第一个变量的时候才开始声明,那将使粗心的程序员迷惑,并且妨碍代码的轻便性voidmyMethod{intint1=0;//beginningofmethodblockifcondition{intint2=0;//beginningofifblock...}}在J__a中,for循环中的指针可以在for语句中声明,例如forinti=0;i__xLoops;i++{...}避免在更高层的声明当中隐含局部声明,例如,不要在一个内部块中声明有相同名字的变量intcount;...myMethod{ifcondition{intcount=0;//__OID!...}...}
6.4声明类和界面当在译码j__a的类和界面的时候,应遵循以下的格式化规则列出参数时,在方法名和圆括号之间不应该有空格{出现在声明语句同一行的结尾}单起一行,但要和最近的“{”匹配但如果是空语句则例外classSampleextendsO__ect{intivar1;intivar2;Sampleintiintj{ivar1=i;ivar2=j;}intemptyMethod{}...}Methods
7、语句7.1简单语句每行最多只能包括一个语句比如argv++;//Correctar__--;//Correctargv++;//ar__--;//__OID7.2复合语句复合语句是包括一系列包含在括号{statement}中的语句请看以下例子被包含的语句必须比复合语句缩进一格开始的括号必须在开始复合语句的那一行的末尾;关闭的括号应该重起一行并相对复合语句的开头来说缩进当括号是控制结构的一部分时,它们在所有语句中使用,像if-elsea或for语句即便是简要语句这使得增加语句非常容易,您也不必为了忘记加括号而付出艰辛的劳动
7.3return语句在某种程度上,如果一个return语句的返回值并不非常明显,那么不应该加圆括号例如return;returnmyDisk.size;returnsizesize:defaultSize;
7.4ifif-elseifelse-ifelse语句if-else语句可以分为以下几类ifcondition{statements;}ifcondition{statements;}else{statements;}ifcondition{statements;}elseifcondition{statements;}else{statements;}Note:ifstatementsalwaysusebra__s{}.__oidthefollowingerror-proneform:ifcondition//__OID!THISOMITSTHEBRA__S{}!statement;
7.5for语句For语句的形式如下所示forinitialization;condition;update{statements;}一条空的for语句的形式如下所示forinitialization;condition;update;当在初始化或更新子句的时,避免使用超过三个以上的变量,如果有必要的话,可以在for循环开始之前或结束后使用个别的语句
7.6while语句while语句的形式如下所示whilecondition{statements;}一个空的while语句的形式如下whilecondition;
7.7do-while语句do-while语句的形式如下do{statements;}whilecondition;
7.8switch语句switchcondition{caseABC:statements;/*fallsthrough*/caseDEF:statements;break;caseXYZ:statements;break;default:statements;break;}每一个switch语句应该包括一个默认的case,在默认的case之中的break是多余的,但是这样可以防止以后另外的case加入而引起的错误
7.9try-catch语句try-catch语句的形式如下所示try{statements;}catchEx__ptionClasse{statements;}
8、空白处8.1空行空行通过分开那些有逻辑关联的编码区来提高可读性两空行的使用总是要遵循如下的操作环境在两个包含源文件的段之间在定义的类和界面之间一空行的使用总是要遵循如下的操作环境在两个程序之间在一程序和它的起始语句中的两个局部变量之间在一程序块或单行注释之前在一程序中用以提高可读性的两逻辑段之间8.2空格空格的使用总是要遵循如下的操作环境一个后跟圆括号的关键词应当以空格来分隔例如whiletrue应注意空格不能使用在一程序名和它的开放式圆括号之间这有助于将关键词从程序指令中识别出来一空格应当出现在参数表中逗号之后所有二进制运算符(除了),都应当从它们的操作数中以空格来分隔空格不能将一元运算符从它们的操作数中分隔开,例如一元减、增量和减量举例如下a+=c+d;a=a+b/c*d;whiled++=s++n++;printSize“sizeis“+foo+“\n”;在for语句中的表达式应当以空格来分隔例如forexpr1;expr2;expr3数据类型转换之后应当跟空格例如myMethodbyteaNumO__ectx;myMethodintcp+5intI+3+1;
9、命名规范命名规范使得程序更易读易懂,同时它们又给出了标识符的功能信息,例如是否是常量、组件或类这对理解代码是极其有用的标识符类型命名规则举例组件一个唯一的组件名前缀总是以全小写的ASCII码表示,并且必须是最高级别的域名之一目前可用comedugovmilnetorg或ISO3166标准
(1981)中规定的用于识别国家的英文两个字母的模式组件名的后继部分因其组织机构内部固有的命名方式而异这些规定说明某一目录名部分可以是区域名、部门名、项目名、机器名或注册名com.sun.engcom.apple.quicktime.v2edu.cmu.cs.bovik.cheese类类名应当是名词,在混合词中内部词第一个字母应当大写尽量保持类名简单易懂又具有说明性使用单词全拼,避免首字母缩略词和缩写词(除非缩写比全拼更广为使用,例如URL或HTML)classRaster;classI__geSprite;界面界面名应当同类名一样大写inte_____RasterDelegate;nte_____Storing程序程序应当是动词,在混合词中起始词小写,每一个内部词第一个字母大写run;runFast;getBackground;变量除了变量,所有实例、类和类常量在混合词中的第一个字母应小写内部词第一个字母大写变量名即便是被允许也不能以下划线-字符或美元符$作起始变量名应当简短而有含义变量名的选取应当是有助于记忆性的,也就是说名字的设计应能指示程序中的临时解析器理解它的使用意图单个字符变量名应当避免,除非是临时的可以随时“丢弃”的变量对于临时变量,通用名可用ijkm和n作为整数,cd和e作为字符inti;charc;floatmyWidth;常量变量名声明类常量和ANSI常量应当用全大写表示,单词之间用下划线(“_”)分隔(为了便于调试,ANSI常量应避免)staticfinalintMIN_WIDTH=4;staticfinalint__X_WIDTH=999;staticfinalintGET_THE_CPU=1;10程序设计惯例
10.1使用实例和类变量没有非常好的理由,请不要声明任何实例或类变量,实例变量经常会在调用方法上起副作用适当的公用实例变量的例子是类实质上是一个数据结构,而不是行为的情况下使用的换句话说,如果你情愿用struct而不用class,那麽使用类的实例变量是恰当的
10.2改进类变量和方法避免用一个对象访问类(静态)变量或方法,用一个类名来代替例如clas__ethod;//OKAClass.clas__ethod;//OKanO__ect.clas__ethod;//__OID!
10.3常量数字常量不应该直接被编码,除了
1、
0、-1,这几个数字常量可以出现在一个for循环中,作为计数值
10.4变量分配在一个单一语句中,避免给一个变量分配同一个值,那会没有可读性例如fooBar.fChar=barFoo.lchar=c;//__OID!在容易误解的地方,不要使用任务操作符ifc++=d++{//__OID!J__adisallows...}应该写成ifc++=d++!=0{...}如果试图提高运行速度,请不要使用包含式的分配,因为这是编译器的工作例如d=a=b+c+r;//__OID!应该写成a=b+c;d=a+r;
10.5混合惯例
10.
5.1圆括号为了避免操作符的优先问题,通常情况下不加限制的使用圆括号(包括混合操作符的情况)是个好办法,即使操作符的优先性对你来说看起来很清晰,因为你们不能猜测,其他的程序员会和你们一样清楚操作符的优先性ifa==bc==d//__OID!ifa==bc==d//RIGHT
10.
5.2返回值尽量使你的程序的结构达到相称的目的,例如ifbooleanExpression{returntrue;}else{returnfalse;}不应该写成returnbooleanExpression;同样的ifcondition{returnx;}returny;不要写成returnconditionx:y;
10.
5.3条件表达式之前的?如果一个含有二进制操作符的表达式出现在?之前,并且为三重的?操作符,应该加上括号,例如x=0x:-x;
10.
5.4特殊注释用XXX作为注释信息来试图标记一些事情,那是不切实际的用FIXME标记某些事情,那也是不切实际的11代码例子
11.1J__A源文件例子下面的例子显示了如何格式化一个包含单一公用类的J__A源文件同样的界面也被格式化,更多的信息请参见ClassandInte_____Declarationsonpage4andDocumentationCommentsonpage9/**@#Blah.j__a
1.8299/03/18**Copyrightc1994-1999SunMicrosystemsInc.*901SanAntonioRoadPaloAltoCalifornia94303U.S.A.*Allrightsreserved.**Thissoftwareistheconfidentialandproprietaryinfor__tionofSun*MicrosystemsInc.ConfidentialInfor__tion.Youshallnot*disclosesuchConfidentialInfor__tionandshalluseitonlyin*accordan__withthetermsoftheli__nseagreementyouenteredinto*withSun.*/packagej__a.blah;importj__a.blah.blahdy.BlahBlah;/***Classdescriptiongoeshere.**@version
1.8218__r1999*@authorFirstnameLastname*/publicclassBlahextendsSomeClass{/*Aclassimplementationcommentcangohere.*//**classVar1documentationcomment*/publicstaticintclassVar1;/***classVar2documentationcommentthathappenstobe*morethanonelinelong*/privatestaticO__ectclassVar2;/**instan__Var1documentationcomment*/publicO__ectinstan__Var1;/**instan__Var2documentationcomment*/protectedintinstan__Var2;/**instan__Var3documentationcomment*/privateO__ect[]instan__Var3;/***...constructorBlahdocumentationcomment...*/publicBlah{//...implementationgoeshere...}/***...methoddoSomethingdocumentationcomment...*/publicvoiddoSomething{//...implementationgoeshere...}/***...methoddoSomethingElsedocumentationcomment...*@paramsomeParamdescription*/publicvoiddoSomethingElseO__ectsomeParam{//...implementationgoeshere...}}。