java开发规范总结_代码注释规范
规范需要平时编码过程中注意,是一个慢慢养成的好习惯
1.基本规则
1.注释应该使代码更加清晰易懂
2.注释要简单明了,只要提供能够明确理解程序所必要的信息就可以了。如果注释太复杂说明程序需要修改调整,使设计更加合理。
3.注释不仅描述程序做了什么, 还要描述为什么要这样做,以及约束
4.对于一般的getter、setter方法不用注释
5.注释不能嵌套
6.生成开发文档的需要用中文编写
2.三种注释方式说明
1.文档注释 /** */
可以对用多行,一般用来对类、接口、成员方法、成员变量、静态字段、静态方法、常量进行说明。Javadoc可以用它来产生代码的文档。为了可读性,可以有缩进和格式控制。
文档注释常采用一些标签进行文档的特定用途描述,用于帮助Javadoc产生文档,常用的有:
标签 |
Used for |
目的 |
@author name |
类/接口 |
描述代码的作者,每个作者对应一个这样的标签 |
@deprecated |
类 成员方法 |
说明该段API已经被废除 |
@exception name description 或 @throws name description |
成员方法 |
描述方法抛出的异常 每个异常一个对应一个这样的标签 |
@param name description |
成员方法 |
描述成员方法中的参数用途和意义,一个参数对应一个这样的标签 |
@return description |
成员方法 |
描述成员方法的返回值的意义 |
@since |
类/接口 成员方法 |
描述该段API开始的时间 |
@see ClassName |
类/接口 成员方法 成员变量 |
用于引用特定的类描述,一般ClassName用包括包名的全名 |
@see ClassName#memberfunction |
类/接口 成员方法 成员变量 |
用于引用特定的类的成员方法的描述,一般ClassName用包括包名的全名 |
@version text |
类/接口 |
版本 |
@inheritDoc |
类/接口 成员方法 |
继承的文档 |
2.行注释 //
一次只能注释一行,一般用来简短的描述某一个局部变量,程序块的作用
3.块注释: /* */
在代码中禁止使用
4.类/接口注释
类/接口描述,一般比较详细。按照常用的说明顺序排列,主要包括
1.类的主要说明,以。或.结束
2.类设计的目标,完成什么样的功能
3.<Strong>主要的类使用</Strong>如何使用该类, 包括环境要求,如是否线程安全,并发性要求, 以及使用约束
4.<Strong>已知的BUG</Strong>
5.描述类的修改历史:<Strong>修改人+日期+简单说明</Strong>
6.@author作者、@version版本, @see参照,@since开始版本等信息如:
/**
* This class provides default implementations for the JFC <code>Action</code>
* interface. Standard behaviors like the get and set methods for
* <code>Action</code> object properties (icon, text, and enabled) are defined
* here. The developer need only subclass this abstract class and
* define the <code>actionPerformed</code> method.
* <p>
* <strong>Warning:</strong>
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is appropriate
* for short term storage or RMI between applications running the same
* version of Swing. A future release of Swing will provide support for
* long term persistence.
*
* @version 1.41 2015/05/26
* @author xxxxx
* @see Action
*/
为了使形成的文档可读性好,注释中经常带有缩进和格式控制。类描述放在类的类定义的紧前面,不能有任何的空行。
3.变量注释
1.成员变量、类静态变量采用文档注释,对成员变量的注释通常包括:
1)变量的意义
2)变量的合法值域
3)对并发访问的限制
如:
/**
* Web.xml文件中configServlet参数的UIAPP.xml initparam
*/
public final static String APP_CONFIG = "aaa.uiapp";
2.局部变量,如算法相关的变量采用块或行注释
public void func() {
int i; //用于循环计数
…………
}
3.参数变量注释一般用文档注释,并且用@param来说明为参数,一般包括
1) 参数的用途
2) 对参数值范围的要求
4.方法注释
描述函数的功能,对成员方法,静态方法一般采用文档描述,特别是公开的方法。注释可以很详细,为了可读性强也可包含格式控制,如下面说明含有缩进:
/**
* Here is a method comment with some very special
* formatting that I want indent(1) to ignore.* */
方法注释一般包括:
1.方法的主要说明,以。或.结束
2.描述方法完成什么样的功能,方法的目标,用该方法的原因
3.描述方法的使用方法,包括使用的环境要求,如前置条件,后置条件和并发性要求
4.描述已知的bug
5.描述方法的修改历史:<Strong>修改人+日期+简单说明</Strong> (<修改人+日期+简单说明>)
6.@param c elements to be inserted into this list.(参数说明)
7.@return <tt>true</tt> if this list changed as a result of the call.(返回值说明)
8.@throws NullPointerException if the specified Collection is null.(异常说明)
9.@see如果重载方法必须参考父类的方法
10Eclips下采用Alt+Shift+J生成Javadoc说明方法的放回值((@return)
5.修改记录
1.在修改一个类前,必须先从SVN中update,之后再进行修改;
2.修改的地方必须加入注释,说明修改人,修改原因,修改内容,修改时间;
java开发规范总结_代码注释规范的更多相关文章
- java开发规范总结_代码编码规范
规范需要平时编码过程中注意,是一个慢慢养成的好习惯 1.基本原则 强制性原则: 1.字符串的拼加操作,必须使用StringBuilder: 2.try…catch的用法 try{ }c ...
- vs2008 多人同时开发项目时的代码注释规范格式 分类: C#小技巧 2014-04-23 14:12 297人阅读 评论(0) 收藏
多人同时开发一个项目,区分项目的那个窗体是谁开发的,例:下面的格式 /************************************************ 模块:服务器设置 ...
- java代码注释规范
java代码注释规范 代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二 ...
- [转]java代码注释规范
代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二期开发中使用的代码注释规范 ...
- PHPDocument 代码注释规范总结
PHPDocument 代码注释规范 1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通 ...
- 完整java开发中JDBC连接数据库代码和步骤[申明:来源于网络]
完整java开发中JDBC连接数据库代码和步骤[申明:来源于网络] 地址:http://blog.csdn.net/qq_35101189/article/details/53729720?ref=m ...
- 代码注释规范-IDEA 配置 Java 类方法注释模板
1. 引言 团队开发时,业务模块分配的越清晰,代码注释管理越完善,越有利于后面维护,后面再管理也方便不少.另外也起着"文字砖"的作用,你懂的.注释不需要很详细,把代码块方法 ...
- 《码处高效:Java开发手册》之代码风格
流水淡,碧天长,鸿雁成行.编码风格,简捷清爽,反引无限风光. 在美剧<硅谷>中有这样一个经典镜头,主人公 Richard 与同为开发工程师的女友闹分手,理由是两人对缩进方式有着截然不同的编 ...
- 代码注释规范之Doxygen
1.Doxygen简介 Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间.当然这里程序中的注释需要遵循一定的规则书写,才能让 ...
随机推荐
- zedGraph
“zedGraph”控件画图的时候遇到了一点小问题,就是在同一个控件实例上第一次绘制饼图的时候一切正常,但是再次绘制的时候不是重新绘制新的饼图,而是在原有基础之上又添加进新的对象(PieItem),又 ...
- OracleHelper[.Net 连接Oracle数据库的封装类]
using System; using System.Configuration; using System.Data; using System.Data.OracleClient; using S ...
- LoadRunner中的参数与变量
在LoadRunner脚本开发中,经常会遇到参数与变量相互转换的情况,本文对常见的转换情形进行了方法总结. 1.变量的赋值 //将字符串赋值给变量 ]; strcpy(strTemp, "H ...
- Web---演示Servlet的相关类、下载技术、线程问题、自定义404页面
Servlet的其他相关类: ServletConfig – 代表Servlet的初始化配置参数. ServletContext – 代表整个Web项目. ServletRequest – 代表用户的 ...
- JavaScript高级程序设计60.pdf
错误处理 try-catch语句 try{ //可能会导致错误的代码 }catch(error){ //在错误发生时如何处理 } error是一个包含着错误信息的对象,它有一个message属性,保存 ...
- asp.net将本地Excel上传到服务器并把数据导入到数据库
前台代码: <td class="formLabel"> 批量修改: </td> <td class="formInput"> ...
- 搜索(DFS)
不知道为什么~除了我室友其他的同学都觉得DFS很简单~且比BFS容易得多........我真心不觉得啊T T~我真心觉得BFS比DFS简单得多................= = 为了把DFS完全搞 ...
- 升级cocoapods到1.2 beta版本的方法
最近写Swfit3.0, 要用到一些框架, 然后就用cocoapods嘛, 结果说要cocoapods1.1.0版本才行, 而自己的是cocoapods1.0.1版本的, 所以就想着升级嘛, 结果就遇 ...
- 基于iOS,Android的服务器证书失效检测
1.前言 在目前的iOS,Android手机上,当手机应用进行SSL通信时,手机端默认是不会进行服务器证书是否失效的监测. 在iOS上,系统是会定期获取所访问服务器的证书信息然后出存在本地. 在And ...
- Java集合类总结
Java的集合类关系图,摘自网络: List: 1,ArrayList:内部采用数组存储结构:随机查找效率高,增删效率低:线程不安全: 2,LinkedList:内部采用链表存储结构:增删效率高,查找 ...