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  表示交叉参考

上一篇:如何在阿里云linux上部署java项目


下一篇:Java基础加强之多线程篇(线程创建与终止、互斥、通信、本地变量)