JAVA代码注释规范

JAVA代码注释规范

一、    规范存在的意义

1.  好的注释规范可以让人一眼看明白这是干什么的，特别是对于我们这种行业；共同合作完成一个项目需要分工明确，所以也需要有明了的注释规范。

2.  正确的应用注释规范可以增加代码的可读性、理解性。

3.  好的代码规范可以提高团队的开发效率，从而节省时间。

4.  长期的坚持代码规范可以让程序员养成一个良好的习惯，甚至锻炼出思维。

二、    命名规范

1.  一般概念

1)  尽量使用完整的英文描述。

2)  采用相对好理解的术语。

3)  采用骆驼命名的规范使名字增加可读性。

4)  尽量少用缩写提高可读性。

5)  避免名字过长。

6)  避免使用类似的名字。

7)  避免使用特殊符号。

2.  主要的运用

1)  类（class）的命名

2)  接口(interface)的命名

+方法(method)的命名

3)  参数(param)的命名

三、    注释规范

1.  一般概念

1)  注释应该增加代码的清晰度

2)  保持代码的整洁

3)  在写代码之前或同时注意写上注释

4)  注释出为什么做这件事，做这件事的结果

2.  注释那些部分

1)  java文件：版权信息、创建时间、创建人

2)  类：目的、所完成功能、版权信息、创建人

3)  方法：参数含义、返回值

4)  属性：字段描述

5)  接口：目的、创建人、版本号、创建时间

四、    代码格式规范

1.  单行注释://注释内容，一般与代码后空4-8格，注释必须对齐

2.  块状注释：/*注释内容*/，一般是注释从以/*开始，以*/结束中的所有内容。

3.  文档注释：/**......*/所以注释文 档必须书写在类、域、构造函数、方法，以及字段(field)定义之前. 注释文档由两部分组成——描述、块标记。

4.  javadoc注释标签

@author    对类的说明 标明开发该类模块的作者
@version   对类的说明 标明该类模块的版本
@see      对类、属性、方法的说明 参考转向，也就是相关主题
@param    对方法的说明 对方法中某参数的说明
@return    对方法的说明 对方法返回值的说明
@exception  对方法的说明 对方法可能抛出的异常进行说明

五、java注释具体实现

1.       源文件注释

/**

*文件名

*创建人

*创建时间

*修改人

*描述

*版本号

*/

2.       类注释

/**

*对此类的描述信息

*创建人

*版本号

*创建时间

*/

3.       方法的注释

/**

*方法的用处

*该方法的参数列

*该方法返回的值

*/

4.       属性的注释

/**

*字段的描述

*/

5.       接口注释

/**

*对此接口的描述

*创建人

*创建时间

*版本号

*/

6.       构造方法注释

/**

*描述该构造方法的用处

*该构造方法的参数列

*参数的类型

*/

 

六、Jsp代码格式规范

1.  多行注释:,一般是注释从以结束中的所有内容。

2.  文本注释:<%-- 内容 --%>,主要是对该页面的一些描述，目的、创建人、创建时间、版本号、文件名、备注、修改人等.

例如:

<%--

-创建人

-创建时间

-版本号

-文件名

-备注

-修改人

--%>

3.  伪劣标签注释:<% java语句块 %>

例如：

<%

JAVA代码块

%>

4.  单行注释：//注释内容，一般与代码后空4-8格，注释必须对齐

七、JS代码格式规范

1.  文本注释:/** 注释内容**/，主要是对该页面的一些描述，目的、创建人、创建时间、版本号、文件名、备注、修改人等. 也可以用于注释代码块。

例如:

/**

*创建人

*创建时间

*版本号

*文件名

*备注

*修改人

**/

 

2.  文本注释:/** 内容 */ ,主要是对该页面的一些描述，目的、创建人、创建时间、版本号、文件名、备注、修改人等.也可以用于注释代码块。

例如:

/**

*创建人

*创建时间

*版本号

*文件名

*备注

*修改人

*/

3.  单行注释: //注释内容，一般与代码后空4-8格，注释必须对齐

4.  多行注释: /* 注释内容 */,一般是注释从以/* 开始，以*/结束中的所有内容。

八、JS注释具体实现

1.       文件注释

/**

*对此文件的描述信息

*创建人

*版本号

*创建时间

*/

2.       方法的注释

/**

*方法的用处

*该方法的参数列

*该方法返回的值

*/

3.       模块的注释

         /**

         *模块名称

         *模块的用处

         */