java编程规范之java注释规范

代码要是没有注释，对读者来说就是一堆乱七八糟的字母，为了提高代码的可读性和可维护性，必须对代码进行必要的注释，这里小编整理了一下java注释规范。

(一)技巧

1：注释当前行快捷方式：ctrl+/

2：/* */ 选上要注释的代码 ctrl+Shift+/

(二)在哪些地方加注释？

1：每个源文件开头都应有一组注释，包含代码的作者，时间；

2：当编写的代码较长，并且包含了多层嵌套时，花括号会比较多，比较乱，为了方便阅读，应该在某些段落结束的地方加注释，注明该闭合花括号对应的起点；

3：每个方法都必须加注释，对方法等进行注释时，注释最好放在代码上方，对变量声明进行注释时，注释最好放在行尾，但多行的行尾注释应该对齐；

4：典型算法必须有注释，代码有bug或不清楚的地方必须加注释，修改过的代码要加修改标志的注释。

(三)注释遵循哪些原则？

1：利用缩进和空行将注释与代码分隔开，是代码与注释在没有颜色提示情况下也能很容易分辨出来；

2：将注释内容与注释分隔符用一个空格隔开，便于查找注释；

3：对多行注释是尽量不用使用/* * /，而是用多行“//”，可以避免查找配对的/* */

(四)注释方法分类

1：单行注释-----//

单独行注释：

当注释需要单独单用一行时，使用“//” 并在注释前留一个空行，缩进情况要与下面的代码一致。一行放不下时使用多行，此时使用/* */进行注释。

行尾注释：

在代码行的行尾加注释，一般要空8个格，且所有注释必须对齐。

2：块注释---/*内容*/

对若干行进行注释，一般放在方法之前，起引导作用，对方法和数据结构等的功能，意义进行说明

/*

*注释内容

*/

3：文档注释

注释若干行，将会形成HTML格式的代码报告，注释文档必须写在类，成员变量，成员方法，构造方法之前，例如下面是一个servlet创建后生成的一个注释文档

/**
	 * The doGet method of the servlet. <br>
	 *
	 * This method is called when a form has its tag value method equals to get.
	 * 
	 * @param request the request send by the client to the server
	 * @param response the response send by the server to the client
	 * @throws ServletException if an error occurred
	 * @throws IOException if an error occurred
	 */
	public void doGet(HttpServletRequest request, HttpServletResponse response)
			throws ServletException, IOException {
                        doPost();
         }

4：类注释

在myEclipse中，可以通过快捷键Alt+Shift+J生成，注释的内容可以通过Eclipse -> Window -> Preferences -> Java -> Code Style -> Code Templates -> Comments -> Types -> Edt 设置

格式如下：

/**
 * @author ASWH
 *
* @Time 2014-3-30-17:33:01   */

类的英文注释模板

/** 
* CopyRright (c)2014-xxxx:   <暗伤无痕 >                          
    * Project:                     <项目工程名 >                                          
* Module ID:   <(模块)类编号，可以引用系统设计中的类编号>    
    * Comments:  <对此类的描述，可以引用系统设计中的描述>                                           
* JDK version used:      <JDK1.7>                              
* Namespace:           <命名空间>                              
* Author：        <作者中文名或拼音缩写>                 
* Create Date：  <创建日期，格式:YYYY-MM-DD> 
* Modified By：   <修改人中文名或拼音缩写>                                         
* Modified Date:  <修改日期，格式:YYYY-MM-DD>                                    
    * Why & What is modified  <修改原因描述>    
* Version:                  <版本号>                       
*/ 

中文模板

/** 
* 文 件 名 : 
    * CopyRright (c) 2014-xxxx: 
* 文件编号： 
* 创 建 人： 
* 日    期： 
* 修 改 人： 
* 日   期： 
* 描   述： 
* 版 本 号： 
*/

7：构造函数注释

  /**

   * 构造方法 的描述

   * @param name

   *       
   */

8：方法注释

/**

   * 生成随机数

   *@param numble

         随机数上限

*@return 

*@exception  (方法有异常的话加)

* @author ASWH

* @Time2014-3-30 17:35:29



   */

9：全局变量注释

 /** The count is the number of charactersin the String. */
   private int count;

有必要是要说明变量功能，涉及到的方法等等。

10：普通变量或常量

//属性

附录：javadoc参数说明：

@see 生成文档中的“参见xx 的条目”的超链接，后边可以加上：“类名”、“完整类名”、“完整类名#方法”。可用于：类、方法、变量注释。
@param 参数的说明。可用于：方法注释。
@return 返回值的说明。可用于：方法注释。
@exception 可能抛出异常的说明。可用于：方法注释。
@version 版本信息。可用于：类注释。
@author 作者名。可用于：类注释。

@deprecated 对类或方法的说明 该类或方法不建议使用,引起不推荐使用的警告

@note 表示注解，暴露给源码阅读者的文档

@remark 表示评论，暴露给客户程序员的文档

@since 表示从那个版本起开始有了这个函数

@see 表示交叉参考