软件开发注释模板说明书V1.0.1

开发注释模板说明书V1.0.1***有限公司软件部201*年*月修改历史记录版本提交人日期备注（说明修改原因、内容、审核结论等）开发注释模板说明书V1.0.1****有限公司-i-目录修改历史记录..................................................................1目录..........................................................................I1.概述.......................................................................11.1.为什么需要开发注释模板.....................................................11.2.预期读者...................................................................11.3.适用范围...................................................................12.模板说明...................................................................12.1.文件注释FILESCOMMENTS.......................................................12.2.类注释TYPESCOMMENTS.........................................................22.3.方法注释METHODSCOMMENTS.....................................................22.4.GETTERS注释GETTERSCOMMENTS....................................................32.5.SETTERS注释SETTERSCOMMENTS....................................................33.模板使用...................................................................33.1模板下载...................................................................43.2模板导入...................................................................43.3添加注释...................................................................53.1.1.添加文件和类注释......................................................53.1.2.添加方法注释..........................................................63.1.3.添加Getters和Setters注释............................................6开发注释模板说明书V1.0.1****有限公司-1-1.概述1.1.为什么需要开发注释模板软件开发规注释对编程人员相当重要，有如下原因：1.程序中的注释是程序设计者与程序阅读者之间通信的重要手段.2.好的注释规范可以尽可能的减少一个软件的维护成本3.好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。4.好的注释规范可以最大限度的提高团队开发的合作效率。5.长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力基于上述原因，编程人员在编码中需要加入统一的注释，方便维护和管理。1.2.预期读者软件部全体成员。1.3.适用范围适用于软件部所有基于JAVA开发的项目。2.模板说明2.1.文件注释FilesComments/***项目名称：${project_name}*文件名称:${file_name}*所属包名:${package_name}*文件描述：*/开发注释模板说明书V1.0.1****有限公司-2-该注释会出现在文件的最上端添加，为整个文件添加注释，注释的内容有一下几项：项目名称：用于说明该文件属于那个项目工程。文件名称：用于说明该文件的文件名。所属包名：用于说明该文件在项目的那个包下，方便其他文件对本文件导入。描述：用于描述该文件的大体功能2.2.类注释TypesComments/***类名称：${type_name}*类描述：*@创建者：${user}*@创建时间：${date}*@变更记录：${date}${time}by变更人*/该注释会出在类的上端，为该类添加注释，注释的内容有一下几项：类名称：用于说明该类的类名。类描述：用于说明该类的功能。@创建者：用于记录该类的创建者。@创建时间：用于记录该类的创建时间。@变更记录：用户记录该类的修改信息2.3.方法注释MethodsComments/***方法名：${enclosing_method}*方法描述：*@参数：参数名参数类型参数描述*@返回值类型：${return_type}*@创建时间：${date}开发注释模板说明书V1.0.1****有限公司-3-*@创建者：${user}*@变更记录：${date}${time}by变更人*/在每个方法的上端都要添加方法注释，注释的内容有一下几项：方法名：用于说明方法的名称。方法描述：用于详细说明该方法的功能。@参数：需要详细说明每个参数的参数名，参数类型，和参数描述@返回值类型：说明该方法的返回值的类型@创建者：用于记录该方法的创建者。@创建时间：用于记录该方法的创建时间。@变更记录：用户记录该类的修改信息2.4.Getters注释GettersComments/***@返回值${bare_field_name}*/在每个实例变量的getter上端都要添加该注释，注释只有一项内容：返回值：用于说明getter方法的返回值名称2.5.Setters注释SettersComments/***@参数参数名${param}参数类型参数说明*/在每个实例变量的setter上端都要添加该注释，注释只有一项内容：参数：需要详细说明setter参数的参数名，参数类型，和参数描述3.模板使用类的方法的代码行数不能过长，尽量控制在100行（90%），长的方法要拆开发注释模板说明书V1.0.1****有限公司-4-分成私有函数。3.1模板下载在SVN中下载“乐食软件开发注释模板.xml”下载路径：svn://****/**软件开发注释模板.xml3.2模板导入打开Myeclipse在标签栏中找到Window--Preferences--Java--CodeStyle--CodeTemplete点击Import按钮，选择“**软件开发注释模板.xml”，即可完成导入开发注释模板说明书V1.0.1****有限公司-5-3.3添加注释3.1.1.添加文件和类注释文件和类注释需要在创建新文件时候生成，选中“Generatecomments”复选框即可开发注释模板说明书V1.0.1****有限公司-6-部分注释内容需要根据情况自行添加或修改3.1.2.添加方法注释在完成方法的编写后，双击方法名，按Shift+ALT+J，即可为方法添加方法注释部分注释内容需要根据情况自行添加或修改3.1.3.添加Getters和Setters注释对于类的实例变量可以直接通过Myeclipse添加Getter和Setter方法并生成注释，操作方法如下。先声明类的实例变量开发注释模板说明书V1.0.1****有限公司-7-在编辑栏内点击鼠标右键或者在标签栏找到Source--GenerateSettersandGetters打开对话框，选中需要生成方法的实例变量点击OK生成。开发注释模板说明书V1.0.1****有限公司-8-