java编程规范之java注释规范

来源：互联网发布：焦大seo视频下载编辑：程序博客网时间：2024/04/30 20:30

代码要是没有注释，对读者来说就是一堆乱七八糟的字母，为了提高代码的可读性和可维护性，必须对代码进行必要的注释，这里小编整理了一下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 表示交叉参考

0 0