关闭

关闭

关闭

封号提示

内容

首页 Java注释规范.doc

Java注释规范.doc

Java注释规范.doc

上传者: 跃海翔空 2012-07-05 评分 0 0 0 0 0 0 暂无简介 简介 举报

简介:本文档为《Java注释规范doc》,可适用于IT/计算机领域,主题内容包含Java代码注释规范、规范存在的意义应用编码规范对于软件本身和软件开发人员而言尤为重要有以下几个原因:、好的编码规范可以尽可能的减少一个软件的维护成符等。

Java代码注释规范、规范存在的意义应用编码规范对于软件本身和软件开发人员而言尤为重要有以下几个原因:、好的编码规范可以尽可能的减少一个软件的维护成本,并且几乎没有任何一个软件在其整个生命周期中均由最初的开发人员来维护、好的编码规范可以改善软件的可读性可以让开发人员尽快而彻底地理解新的代码、好的编码规范可以最大限度的提高团队开发的合作效率、长期的规范性编码还可以让开发人员养成好的编码习惯甚至锻炼出更加严谨的思维二、命名规范   、一般概念、尽量使用完整的英文描述符      、采用适用于相关领域的术语      、采用大小写混合使名字可读      、尽量少用缩写但如果用了必须符合整个工程中的统一定义      、避免使用长的名字(小于个字母为正常选择)      、避免使用类似的名字或者仅仅是大小写不同的名字      、避免使用下划线(除静态常量等)、标识符类型说明、包(Package)的命名         Package的名字应该采用完整的英文描述符都是由一个小写单词组成。并且包名的前缀总是一个顶级域名通常是com、edu、gov、mil、net、org等         如:comyjhmilytest、类(Class)的命名         类名应该是个一名词采用大小写混合的方式每个单词的首字母大写。尽量保证类名简洁而富于描述。使用完整单词避免缩写词(除非工程内有统一缩写规范或该缩写词被更广泛使用像URLHTML)      如:FileDescription、接口(Interface)的命名         基本与Class的命名规范类似。在满足Classd命名规则的基础之上保证开头第一个字母为”I”便于与普通的Class区别开。其实现类名称取接口名的第二个字母到最后且满足类名的命名规范      如:IMenuEngine、枚举(Enum)的命名         基本与Class的命名规范类似。在满足Classd命名规则的基础之上保证开头第一个字母为”E”便于与普通的Class区别开。      如:EUserRole、异常(Exception)的命名         异常(Exception)通常采用字母e表示异常对于自定义的异常类其后缀必须为Exception      如:BusinessException、方法(Method)的命名         方法名是一个动词采用大小写混合的方式第一个单词的首字母小写其后单词的首字母大写。方法名尽可能的描述出该方法的动作行为。返回类型为Boolean值的方法一般由“is”或“has”来开头      如:getCurrentUser()、addUser()、hasAuthority()、参数(Param)的命名         第一个单词的首字母小写其后单词的首字母大写。参数量名不允许以下划线或美元符号开头虽然这在语法上是允许的。参数名应简短且富于描述。      如:publicUserContextgetLoginUser(StringloginName)、常量字段(Constants)的命名         静态常量字段(staticfinal)全部采用大写字母单词之间用下划线分隔      如:publicstaticfinalLongFEEDBACK       publicstaticLongUSERSTATUS三、注释规范一个很好的可遵循的有关注释的经验法则是:         问问你自己你如果从未见过这段代码要在合理的时间内有效地明白这段代码你需要一些什么信息???、一般概念           、注释应该增加代码的清晰度         、保持注释的简洁         、在写代码之前或同时写注释         、注释出为什么做了一些事而不仅仅是做了什么、注释哪些部分、Java文件:必须写明版权信息以及该文件的创建时间和作者         、类:类的目的、即类所完成的功能以及该类创建的时间和作者名称多人一次编辑或修改同一个类时应在作者名称处出现多人的名称         、接口:在满足类注释的基础之上接口注释应该包含设置接口的目的、它应如何被使用以及如何不被使用。在接口注释清楚的前提下对应的实现类可以不加注释         、方法注释:对于设置(Set方法)与获取(Get方法)成员的方法在成员变量已有说明的情况下可以不加注释普通成员方法要求说明完成什么功能参数含义是什么且返回值什么另外方法的创建时间必须注释清楚为将来的维护和阅读提供宝贵线索         、方法内部注释:控制结构代码做了些什么以及为什么这样做处理顺序等特别是复杂的逻辑处理部分要尽可能的给出详细的注释         、参数:参数含义、及其它任何约束或前提条件         、属性:字段描述         、局部(中间)变量:无特别意义的情况下不加注释      、注释格式           遵循工程规定的统一注释格式一般情况下会以codetemplatesxml格式的文件导入IDE(Eclipse)或者用Eclipse默认的四、代码格式规范    遵循工程规定的统一代码格式一般情况下直接使用IDE(Eclipse)自带的默认代码格式对代码进行格式化、单行(singleline)短注释:……   单独行注释:在代码中单起一行注释注释前最好有一行空行并与其后的代码具有一样的缩进层级。如果单行无法完成则应采用块注释。注释格式:*注释内容*行头注释:在代码行的开头进行注释。主要为了使该行代码失去意义。注释格式:注释内容行尾注释:尾端(trailing)极短的注释在代码行的行尾进行注释。一般与代码行后空(至少)个格所有注释必须对齐。注释格式:代码(至少)个空格注释内容、块(block)块注释:*……*注释若干行通常用于提供文件、方法、数据结构等的意义与用途的说明或者算法的描述。一般位于一个文件或者一个方法的前面起到引导的作用也可以根据需要放在合适的位置。这种域注释不会出现在HTML报告中。注释格式通常写成:**注释内容*、文档注释:**……*注释若干行并写入javadoc文档。每个文档注释都会被置于注释定界符***之中注释文档将用来生成HTML格式的代码报告所以注释文档必须书写在类、域、构造函数、方法以及字段(field)定义之前。注释文档由两部分组成描述、块标记。注释文档的格式如下:***ThedoGetmethodoftheservlet*Thismethodiscalledwhenaformhasitstagvaluemethod *equalstoget*paramrequest* therequestsendbytheclienttotheserver*paramresponse* theresponsesendbytheservertotheclient*throwsServletException* ifanerroroccurred*throwsIOException* ifanerroroccurred*publicvoiddoGet(HttpServletRequestrequest,HttpServletResponseresponse)throwsServletException,IOException{   doPost(request,response)}前两行为描述描述完毕后由符号起头为块标记注释。更多有关文档注释和javadoc的详细资料参见javadoc的主页:http:javasuncomjavadocindexhtml、javadoc注释标签语法author   对类的说明标明开发该类模块的作者version  对类的说明标明该类模块的版本see     对类、属性、方法的说明参考转向也就是相关主题param   对方法的说明对方法中某参数的说明return   对方法的说明对方法返回值的说明exception 对方法的说明对方法可能抛出的异常进行说明五、JAVA注释具体实现、源文件注释源文件注释采用**……*在每个源文件的头部要有必要的注释信息包括:文件名文件编号版本号作者创建时间文件描述包括本文件历史修改记录等。中文注释模版:***文件名:*CopyRright(c)xxxx:*文件编号:*创建人:*日   期:*修改人:*日  期:*描  述:*版本号:*、类(模块)注释:类(模块)注释采用**……*在每个类(模块)的头部要有必要的注释信息包括:工程名类(模块)编号命名空间类可以运行的JDK版本版本号作者创建时间类(模块)功能描述(如功能、主要算法、内部各部分之间的关系、该类与其类的关系等必要时还要有一些如特别的软硬件要求等说明)主要函数或过程清单及本类(模块)历史修改记录等。英文注释模版:***CopyRright(c)xxxx:  <展望软件Forsoft>                         *Project:                    <项目工程名>                                         *ModuleID:  <(模块)类编号可以引用系统设计中的类编号>    *Comments: <对此类的描述可以引用系统设计中的描述>        *JDKversionused:     <JDK>                             *Namespace:          <命名空间>                             *Author:       <作者中文名或拼音缩写>                *CreateDate: <创建日期格式:YYYYMMDD>*ModifiedBy:  <修改人中文名或拼音缩写>                                        *ModifiedDate: <修改日期格式:YYYYMMDD>                                   *WhyWhatismodified <修改原因描述>   *Version:                 <版本号>                      *如果模块只进行部分少量代码的修改时则每次修改须添加以下注释:RewriterRewriteDate:<修改日期:格式YYYYMMDD>Start:*原代码内容*End:将原代码内容注释掉然后添加新代码使用以下注释:AddedbyAdddate:<添加日期格式:YYYYMMDD>Start:End:如果模块输入输出参数或功能结构有较大修改则每次修改必须添加以下注释:LogID:<Log编号,从开始一次增加>Depiction:<对此修改的描述>Writer:修改者中文名RewriteDate:<模块修改日期格式:YYYYMMDD>、接口注释:接口注释采用**……*在满足类注释的基础之上接口注释应该包含描述接口的目的、它应如何被使用以及如何不被使用块标记部分必须注明作者和版本。在接口注释清楚的前提下对应的实现类可以不加注释。、构造函数注释:构造函数注释采用**……*描述部分注明构造函数的作用不一定有块标记部分。注释模版一:***默认构造函数*注释模版二:***Description:      带参数构造函数,*                      初始化模式名,名称和数据源类型*paramschema:  模式名*paramname:  名称*paramtype:数据源类型*、函数注释:函数注释采用**……*在每个函数或者过程的前面要有必要的注释信息包括:函数或过程名称功能描述输入、输出及返回值说明调用关系及被调用关系说明等。函数注释里面可以不出现版本号(version)。注释模版一:** *函数名: *功能描述:*输入参数:    <按照参数定义顺序>*            <param后面空格后跟着参数的变量名字*           (不是类型)空格后跟着对该参数的描述。>**返回值: 类型<说明>*           <返回为空(void)的构造函数或者函数*           return可以省略如果返回值就是输入参数必须*           用与输入参数的param相同的描述信息必要的时*           候注明特殊条件写的返回值。>*异   常:<按照异常名字的字母顺序>*创建人:*日   期:*修改人:*日   期:*注释模版二:***FunName:          getFirstSpell*Description:     获取汉字拼音首字母的字符串*                  被生成百家姓函数调用*param:        strtheString是包含汉字的字符串*returnString:汉字返回拼音首字母字符串*                 英文字母返回对应的大写字母*                其他非简体汉字返回''*Author:      ghc*CreateDate:*、方法注释:方法注释采用**……*对于设置(Set方法)与获取(Get方法)成员的方法在成员变量已有说明的情况下可以不加注释普通成员方法要求说明完成什么功能参数含义是什么且返回值什么另外方法的创建时间必须注释清楚为将来的维护和阅读提供宝贵线索。、方法内部注释:控制结构代码做了些什么以及为什么这样做处理顺序等特别是复杂的逻辑处理部分要尽可能的给出详细的注释。、全局变量注释:要有较详细的注释包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。、局部(中间)变量注释:主要变量必须有注释无特别意义的情况下可以不加注释。、实参参数注释:参数含义、及其它任何约束或前提条件。、字段属性注释:字段描述属性说明。、常量:常量通常具有一定的实际意义要定义相应说明。myeclipse的注释相关对java文件的自动注释Window>Preference->Java>CodeStyle>CodeTemplatesfiles:新建文件时的注释Types:类的注视Field:变量的注释Constructors:构造函数的注释methods:一般方法的注释可以在里edit一些固定的格式或变量其中user默认取操作系统的名称可以写死。日期格式俺想知道怎么改成yyyymmdd对JSP文件的注释Window>PreferencemyeclipseeditorsJSPJSPTEMPLATES 在java中用的一些快捷例:sysoutWindow>Preferencejavaeditortemplates可以自己写一些参数~例如userzhongjb六、工程特有命名规范、持久层           、Hibernate映射文件及实体            与数据库表名称完全对应            如:Advertisementhbmxml、Advertisementjava         、数据访问DAO            DAO接口和实现类名称必须完全符合正常接口和实现类的命名规则且最后以”DAO”结尾。DAO内的数据访问方法必须足够抽象的描述出对数据库的基本CRUD操作            如:ICrossAdDAO(接口)、CrossAdDAO(实现类)         、各种操作数据库的HQL配置文件            HQL文件的个数原则上与系统的Services层的服务个数相等且以服务名称命名HQL文件            如:resourcehbmxml      、服务层           、服务接口和实现            服务接口和实现类必须完全符合正常接口和实现类的命名规则以工程定义的服务名为主体并统一以”Serv”结尾            如:IResourceServ(服务接口)、ResourceServ(接口实现类)         、服务接口方法            方法名是一个动词采用大小写混合的方式第一个单词的首字母小写其后单词的首字母大写。        方法名尽可能的描述出该方法的动作行为。            返回类型为Boolean值:用“is”或“has”来开头            得到某数据:get数据描述名词复数数据类型            得到所有数据:getAll数据描述名词复数数据类型            通过XXX得到查询某数据:getquery数据描述名词复数数据类型By条件            添加某数据:saveadd数据描述名词()            更新某数据:saveupdate数据描述名词            删除某数据:deleteremove数据描述名词         、业务对象            业务名称BO         、查询参数对象            凡是继承Abst***QuerySpec的查询参数类全部满足以下规则:            Query所要查询的数据描述名词Spec            作为参数传入时参数名必须为:所要查询的数据描述名词Spec            如:QueryProgramSpec      、MVC层                      、Action控制层            Action类名:功能模块名称Action            Actoin方法名称尽可能的描述出页面迁移的去向            如:LoginAction(登录用action)toWelcome(转向欢迎页的action方法)         、资源文件            系统全局资源文件:globalMessages字符编码类型properties            功能模块内部的资源文件:packageproperties 、Spring配置文件           、Action相关配置文件       文件目录:WebRootWEBINFspringaction功能模块名称ApplicationContextxml         、Services相关配置文件      文件目录:WebRootWEBINFspringservicesServicesApplicationContextxml         、全局性配置文件        文件目录:WebRootWEBINFspring工程名ApplicationContextxml 、JSP文件     采用完整的英文描述说明JSP所完成的功能尽可能包括一个生动的动词第一个字母小写如:viewMessagejsp、editUserjsp等。、Java的面向对象。、多线程、网络通信、反射。、类初始化的内存运行情况。、Java对象从创建到消失的全部细节。、独立编写五子棋、梭哈、桌面弹球小游戏。、可以开发Tomact和Struts、Spring、Hiberate框架。、为什么要使用这些技术使用这些技术有什么好处不使用行不行?、为何一个JSP可以向多个页面提供服务?如何开发web服务器?、Spring容器的作用、如何开发Spring容器?、软件开发的全部步骤。、首先为什么是public?因为要在类外面调用main()所以是public、为什么是static?因为系统开始执行一个程序前,并没有创建main()方法所在类的实例对象,它只能通过类名类调用主方法main()作为程序入口,所以该方法是static、为什么是void因为主方法没有返回值、为什么main主方法名、为什么是Stringargs或者Stringargs这表示给主方法传一个字符串数组,字符串名是argsJava中重要的类库javalangjavaiojavanetjavaappletjavaawtjavamathjavaxswingjavautil

热点搜索换一换

用户评论(0)

0/200

精彩专题

上传我的资料

每篇奖励 +2积分

资料评价:

/12
1下载券 下载 加入VIP, 送下载券

意见
反馈

立即扫码关注

爱问共享资料微信公众号

返回
顶部