J2EE项目代码规范文档.doc

项目代码规范文档版本 14 / 14修订历史记录日期版本说明作者20XX-12-5王悦邦20XX-12-6王悦邦20XX-07-15苏谟目录文件名与文件组织结构矚慫润厲钐瘗睞枥庑赖賃軔朧。文件注释头.包的声明与引用.类与接口的声明源文件编排格式.代码行长度与折行规则.代码行长度.折行规则.程序注释.程序实现代码注释.注释规则.变量的声明初始化与放置.变量声明.变量初始化.变量放置程序语句编写规则.简单语句.复合语句.空格与空行的应用规则.空格的应用规则.空行的应用规则.方法、变量与常量的命名规则.方法的命名规则.变量的命名规则.常量的命名规则序通常说来优秀的开发人员一般都有良好的程序设计风格，优秀的管理人员会在自己的开发团队中灌输养成良好程序设计风格的意识，优秀的软件企业都有自己一套健全、成熟的程序设计风格规范文档，用以规范开发人员编写代码的风格。聞創沟燴鐺險爱氇谴净祸測樅。定义这个规范的目的是让项目中所有的代码、文档都具有统一的风格，增加程序的可读性，减少项目组中因为任务移交等原因造成的时间浪费，提高代码的可维护性。残骛楼諍锩瀨濟溆塹籟婭骒東。文件名与文件组织结构文件名由实意文件名后缀组成，后缀名因类型的不同而不同。如表所示。表 后缀名的意义文件类型后缀名源文件字节码文件一般说来源文件的结构是这样的，每一节代码之间是由一个空行分割开的，并且每一节都有相应的注释，通常来讲一个源文件不应该超过行，否则就是视为类“臃肿”，这种情况在程序设计时，应该尽量避免。酽锕极額閉镇桧猪訣锥顧荭钯。每一个源文件一般由下面的顺序构成：（）文件注释头（）包名（）（）引入（）声明（）类（）或接口（）的声明部分文件注释头类文件注释头是用来描述该类功能及其特点，以及相关开发信息的，如该类的关联类（通常情况下不描述系统核心类如, 等）、开发公司或单位、版权、作者、代码审定人该类所支持的版本、该类版本、开发日期、最后更改日期、修改人、复审人等信息。主要用到的注释有：彈贸摄尔霁毙攬砖卤庑诒尔肤。使用格式空格类名（不能带） 版本号 作者 自从（标识类从什么版本开始使用比如：版本新增类，可以使用这个注释进行说明） 开发日期*继承，实现接口，被继承，会自动生成下面就是一个类文件注释头：*謀荞抟箧飆鐸怼类蒋薔點鉍杂。 * 该类功能及其特点的描述（例如：该类是用来实现页面调转） * * 该类经编译测试过 * * （与该类相关联的类）：（例如：） * 开发公司或单位：中科院沈阳计算所有限公司西南信息中心* 版权：本文件版权归属中科院沈阳计算所有限公司* * （作者）：王悦邦 * * （该文件所支持的版本）：* （版本）： * * （开发日期）：20XX-9-6* 最后更改日期：20XX-12-6* 修改人：王悦邦* 复审人：*厦礴恳蹒骈時盡继價骚卺癩龔。文件注释头包括, , , , 等标记，是为了通过声称 标准文档做准备的。茕桢广鳓鯡选块网羈泪镀齐鈞。包的声明与引用我们在做开发时常会引用（）核心类或者第三方软件厂商的类，一般情况下，这些类都是封装在一个包（）里面的，包概念的出现，使类（）有了名称空间的细致划分，使庞大复杂的类群有了较为清晰的分支，形成了清晰脉络。包的另一个作用就是可以将同名的类（）或接口（）分离开来，不至于产生二义性或以假乱真的错误。鹅娅尽損鹌惨歷茏鴛賴縈诘聾。下面给出了包的基本命名规则，之所以说是基本，是因为可以在特殊的情况下采用特殊的命名方法，凡事应具体情况具体分析。一般有如下规则：籟丛妈羥为贍偾蛏练淨槠挞曉。包名应该是独一无二不可重复的；包名通常情况下都应该是小写字母；包名一般是公司域名的倒序，经常用到的域名后缀有, , , , , , 等；預頌圣鉉儐歲龈讶骅籴買闥龅。域名之前的国家名称可以由一到两个英文字母做前缀用来表示国家名称，这个规则可以参考标准；域名后面的部分可以根据习惯命名。一般情况下源文件的第一行都是类本身的包名描述部分（如果有包名的话）。在这之后就是我们引用系统核心包或第三方包的描述部分。例如：渗釤呛俨匀谔鱉调硯錦鋇絨钞。 ; ; ;类与接口的声明类与接口可以说是程序设计中的核心成员，任何采用开发的应用都离不开他们，关于类与接口的声明规则如表所示。铙誅卧泻噦圣骋贶頂廡缝勵罴。表 类与接口的声明序号类与接口的声明声明规则类与接口文件头的注释应采用（*）的注释格式具体的书写格式及其内容，参考部分类与接口的声明类与接口的名字一般由大写字母开头，其他字母都小写的单词组成，并且类的名字应尽量具有清晰的实际意义类与接口实现部分的注释应采用（*）的注释格式这种注释方式一般适用于类的接口中较大区域的注释，而对类与接口文件头的注释，则不适用类的变量的声明首先应该声明公共（）类型的变量，再声明保护（）类型的变量，最后声明私有（）类型的变量实例（）变量的声明与类的变量声明顺序一样，首先应该声明公共（）类型的变量，再声明保护（）类型的变量，最后声明私有（）类型的变量构造器（）的声明构造器一般作为类的第一个方法声明，你可以在构造器的声明体中加入一些与处理代码方法（）的声明方法的声明最好采用以功能性分组的方式进行排列，这比采用可访问性分组的方式排列更为友好，例如：可以将一个私有方法放在两个公共方法之间，这样做是为了把功能性相近的方法排列在一个组中。这样做的目的是为了使代码具有更强的可读性与易解性析构器（）()方法其实程序设计中，本来没有析构器的概念，我们这里只是形象称()方法为析构器。在遵从表中的声明规则的基础上，还要注意方法与方法之间都插入一个空白行，这样代码看起来会更清楚一些，显得更有条理，轮廓更为清晰，增强了程序的可读性。擁締凤袜备訊顎轮烂蔷報赢无。源文件编排格式源文件的一般编排格式中的行间缩紧，是以四个空格键（）为单位的，当然这并没有权威的文献可做参考，只是对一般情况而言是这样的，这样看起来代码格式更清晰、更具美感。四个空格键相当于半个键。在顶头代码行的下属第二行，通常是一个键，即个空格键。贓熱俣阃歲匱阊邺镓騷鯛汉鼉。代码行长度与折行规则代码行长度一般来说的代码行长度应该小于个字符，超过这个长度可能在一些开发工具或编译器上就无法很好地显示，而且也会给阅读程序带来麻烦。因此，我们应尽量避免超过个字符长度的代码行。在一些文档编辑器中惯用长度普遍为个字符左右。坛摶乡囂忏蒌鍥铃氈淚跻馱釣。折行规则当完整的一行代码难以编排在同一个代码行中时，我们可以根据下面的规则，对源代码进行折行编排：在逗号后折行；在运算符（）前折行；高层折行优于底层折行；折下的代码行应该与其同等级的代码行左对齐。如果上面的法则另代码行右侧距页边的距离，差距较大并且混乱，我们可以在适当行采用键（空格键）处理。蜡變黲癟報伥铉锚鈰赘籜葦繯。看以下的应用实例：方法调用折行实例。(, , ,買鲷鴯譖昙膚遙闫撷凄届嬌擻。, ); (, (, ,);运算符前折行与高层折行优于低层折行实例。 * ( ) * *良好的风格*此例中我们采用了折行规则中的折行原则：高层折行优于底层折行。这样做的好处是能使程序的结构更清楚，更容易被人理解。綾镝鯛駕櫬鹕踪韦辚糴飙钪麦。键（空格键）处理法则：*习惯深度折行*( , , ,驅踬髏彦浃绥譎饴憂锦諑琼针。 ) .* 键（空格键）深度折行* ( ,猫虿驢绘燈鮒诛髅貺庑献鵬缩。 , , ) .以上两个方法的折行都是可以接受的，但是第二种折行风格更美观一些。当你在利用空格键缩进时可能会看上去比较费劲，此时你可以采用键（空格键）处理规则。锹籁饗迳琐筆襖鸥娅薔嗚訝摈。程序注释注释在程序中是相当重要的一部分，注释的目的在于说明程序，给自己或他人在阅读程序时提供帮助，使程序更容易理解，也就是增强程序代码的可读性。严格意义上说一份代码应该有的注释内容，我们要求一份代码有不少与的注释量。構氽頑黉碩饨荠龈话骛門戲鷯。注释在程序中分为两类：程序头注释与程序实现代码注释。程序头注释参考部分的内容，下面主要提供程序实现代码注释的原则。輒峄陽檉簖疖網儂號泶蛴镧釃。程序实现代码注释程序实现代码注释一般分为两种风格：块注释与行注释。块注释代码块注释经常被用于提供文件、方法、数据结构、变量的意义与用途，以及算法的描述。块注释一般位于一个文件或一个方法的前面，当然如需要它可以位于任意的地方，如方法体内。尧侧閆繭絳闕绚勵蜆贅瀝纰縭。方法块注释以* 开头以*结尾主要用到的注释有 参数注释,（可重复使用）使用格式 空格参数名空格注释信息 参见(可重复使用) 返回注册（是对返回对象的一个说明） 自从（从哪个版本开始使用的，一个注释） 抛出异常 空格类名抛出异常 空格类名*方法内的局部变量在生成帮助文档的时候不自动生成* * 这个方法是测试方法 * 版本版本以后开始使用 * 类名是 * 我是抛出的异常 * 我是参数的注释 * 我是参数的注释 * 我是对象的注释 * ( ) * * 我是局部变量的注释 * ; ;注：标签后边空格类名，空格注释：但是注释会把类名覆盖掉，所以最好不加注释，只写类名。方法内块注释位于方法体内的块注释应该与其所描述的代码位于同一个层次上。在一个块注释之前一般有一空白行用于做区分代码与注释的边界。块注释以“*”开始，以“*”终结，例如：识饒鎂錕缢灩筧嚌俨淒侬减攙。 * 进行权限判断* (,);凍鈹鋨劳臘锴痫婦胫籴铍賄鹗。() (); 行注释行注释又分为三种：单独行注释、行尾注释与行头注释。之所以把他们统称为行注释，因为它们的注释风格都不换行，都在同一行内。恥諤銪灭萦欢煬鞏鹜錦聰櫻郐。单独行注释在实现代码中单起一行书写注释信息。单独行注释一般用于对较短的注释信息的描述。例如： ()* 处理代码模块*行尾注释行尾注释与单独行注释类似，所不同的是单独行注释要单起一行，而行尾注释则紧跟在这一行代码之后进行注释，原则上代码与注释存在于不可分割的统一行，但为了使代码更加清晰，我们一般采用“代码行键（个空格字符）行尾注释”的格式编排程序。例如：鯊腎鑰诎褳鉀沩懼統庫摇饬缗。 ( ) ; * 如果等于则返回真* * 如果不等于则返回假*行头注释行头注释是用来注释代码的，使代码失去意义，行头注释在程序调试中经常被用到，如果注释的代码行过多并且更改频繁，请采用块注释以提高效率。例如：硕癘鄴颃诌攆檸攜驤蔹鸶胶据。 ( )*做相应处理* ;*否则返回假* ( ) *做相应处理* ; *否则返回假* 类注释与注释在方法的上方注释对此方法的描述、返回值。可以方便快速的了解此方法的用途。例如：* * 获得备注 * 备注 * () ;* * 设置备注 * ( ) ;在方法的上方注释对此方法的描述、参数、返回值。使用户可以方便快速的了解此方法的用途。例如：* * 实现举报信息查询全部信息功能 * 举报投诉 * 权限 * 查询后的信息 * ( )阌擻輳嬪諫迁择楨秘騖輛埙鵜。 ( ) ; ;氬嚕躑竄贸恳彈瀘颔澩纷釓鄧。 () 釷鹆資贏車贖孙滅獅赘慶獷緞。 ; ; (); ;注释规则注释是对代码的“提示”，而不是文档；如果代码本来就是清楚的，则不必加注释；边写代码边加注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除；注释应当准确、易懂，防止注释有二义性；尽量避免在注释中使用缩写，特别是不常用的缩写；注释的位置应与被描述的代码相邻，可以放在代码的上方或右方，不可放在下方；当代码比较长，特别是有多重潜逃时，应当在一些段落的结束处加注释，便于程序的阅读。完整的包括文件注释头和实现代码注释的代码风格如下所示：*怂阐譜鯪迳導嘯畫長凉馴鸨撟。 * 类用来实现事故基本信息操作 * * 该类经编译测试过 * * ： * 开发公司或单位：中科院沈阳计算所有限公司西南信息中心* 版权：本文件版权归属中科院沈阳计算所有限公司* * ：王悦邦 * * ：* ： * * ：20XX-9-6* 最后更改日期：20XX-12-6* 修改人：王悦邦* 复审人：*谚辞調担鈧谄动禪泻類谨觋鸾。 ; ; * （方法注释）录入事故基本信息* 版本后开始使用* * * 事故基本信息* 保存成功与否标志*( )* （块注释）生成事故记录编号* (); （变量说明）事故记录编号 （变量说明）编号标示(); ();();(事故记录编号); ( () 嘰觐詿缧铴嗫偽純铪锩癱恳迹。 ()*（行注释）时间类型转换* 变量的声明初始化与放置变量声明变量的声明在一般情况下要求每一行代码，只声明一个变量，如下所示：*部门级别* ; 部门级别*部门人数* ; 部门人数如果变量名称较短并且又是同一数据类型，下面的声明方式也是可以接受的： , ; 变量初始化尽量在变量声明的地方初始化，如果变量的初始化与有待于计算或处理后的值有关，则我们可以在取得这个值后对变量作初始化。这是程序设计中的一个重要的编程规则。熒绐譏钲鏌觶鷹緇機库圆鍰缄。变量放置尽量把变量声明代码放置在一个代码块的开始处，这里所说的代码块是用括起来的代码段，不要等到在使用变量的时候再声明它，这样会降低代码的可读性与便携性（）。下面给出一段标准的实现变量的代码样例：鶼渍螻偉阅劍鲰腎邏蘞阕簣择。 () ; *代码段起始部位* () ; *代码段起始部位* 这个规则的一个例外就是在循环语句中可以直接声明变量，如下所示： ( ; ”、“”、“”、“*”、“”、“”、“”、“”、“”等操作符的前后应当加空格。仓嫗盤紲嘱珑詁鍬齊驁絛鯛鱧。一元操作符如“！”、“”、“”、“”、“”等前后不加空格。象“”、“.”这类操作符前后不加空格。空行的应用规则空行起着分隔程序段落的作用。在逻辑上相关联的代码块之间合理地插入空行可以增强程序代码的可读性，其规则如下：绽萬璉轆娛閬蛏