首页 > Java技术, 项目管理 > java项目开发规范-注释规范
201210月15

java项目开发规范-注释规范

引言

"(program(computers) == *art) ? so : what"
"只有大约5%的程序员能够在编写代码时创造出艺术。
其他95%一定是为了取得成功的科学家,不是艺术家。"

谈及“艺术”,人们自然会联想到“美”、“技艺”、“灵感”等词,但很少会把它和“计算机编程”这听起来似乎无趣的词联系在一起。而Donald Knuth,《计算机编程的艺术》多卷书的作者,通过他的著作,成功地展现了计算机编程的艺术。
代码实际上是一门技术。编写优美的程序需要灵感和高超的技巧,就像诗人写诗,画家作画,建筑师构筑,充满了乐趣、挑战和美。优雅的程序会像诗歌一样耐人寻味,像名画那样大开眼界,像教堂一样堂皇华丽。所以,计算机编程也同样是一门艺术,程序员就是创造这种艺术的艺术家。
程序虽然是一门艺术,但是也需要遵循一定的规范,如果不遵循一定的规范,那么你创造的艺术将不能得到其它程序员的认可,从而会被很快遗弃。从而会影响整个项目、甚至行业的进展

注释规范

一、配置文件注释
1、Properties资源文件
文件头注释,要包含作者信息

###########################
###配置文件描述:内容描述
###作者:XXX
###创建时间:2010-01-01
###########################

文件内容分组注释

###类别管理start###
###零部件类别###
Category.0=0,零件类别
###材料费分类###
Category.1=1,材料费分类
###任务类别###
Category.2=2,任务类别
###分厂类别###
Category.3=3,分厂类别
###类别管理end###

其中的KEY值和Value值必须一一对应。不要出现空值的现象
每增加一行都应该有一个注释,由三个#开头和结尾
2、Xml配置文件
文件头注释,要包含作者信息,放在字符集声明的后面

<?xml version="1.0" encoding="UTF-8" ?>
<!-- /*  * 配置文件描述:内容描述  * 作者:XXX  * 创建时间:2010-01-01  */ -->

二、Java文件注释
1、文件注释(Files)

/**
 * @Project: ${project_name}
 * @Title: ${type_name}
 * @Package ${package_name}
 * @Description: ${todo}
 * @Company: 乐购科技信息技术有限公司
 * @author ${user} ${user}@itblood.com
 * @date ${date} ${time}
 * @Copyright: ${year}
 * @version V1.0
*/

2、类注释(Types)

/**
 * @ClassName: ${type_name}
 * @Description: ${todo} (请用一句话描述该类做什么)
 * @author ${user} ${user}@itblood.com
 * @date: ${date} ${time}
 * ${tags}
*/

3、方法注释

/**
 * @Title: ${enclosing_method}
 * @Description: ${todo}
 * @author: ${user} ${user}@itblood.com
 * @date: ${date} ${time}
 * @return ${return_type}
 * @throws
*/

4、方法修改注释
自己在修改别人的代码时,需要注释;
虽然是自己的代码,但出现了大的业务改动,需要注释
修改方法:
1) 对于在类中增加或删除方法,需要在类注释中记录变更信息
2) 对于类的方法的修改,需要在方法注释中记录变更信息
3) 在注释中的author一栏中加入修改人、修改时间和修改原因及主要内容

/**
 * @Title: ${enclosing_method}
 * @Description: ${todo}
 * @author: ${user} ${user}@itblood.com
 * @date: ${date} ${time}
 * @param ${tags}
 * @return ${return_type}
 * @throws
 * @modified by ${user} ${user}@itblood.com
 * @modified date ${date} ${time}
 * @@modified description ${todo}
*/

5、类成员变量
类成员变量及常量使用以下方式进行注释,该注释信息体现在javadoc自动生成文档中
1) 注释需要写在对应代码的上方,之间不允许空行
2) 如果注释在一行内,采用这样的注释

/** 变量的说明 */

3) 如果注释在多行内,采用这样的注释

/**
* 变量的说明
*
*/

6、方法成员变量
类方法中的局部变量注释方式如下,该注释信息不体现在javadoc生成文档中
1) 注释需要写在对应代码的上方,之间不允许空行
2) 如果注释在一行内,采用这样的注释

/* 变量的说明 */ 或者 //变量的说明

3) 如果注释在多行内,采用这样的注释

/*
 * 变量的说明
 *
*/

三、Jsp文件注释
应该在JSP文件中字符集声明的后面,应遵守这样的规范,此方式注释JSP引擎会自动忽略,不会被发送到客户端

四、Javascript注释
1、头部注释

/**
 * @Description: ${todo}
 * @Company: 乐购科技信息技术有限公司
 * @author ${user} ${user}@itblood.com
 * @date ${date} ${time}
 * @version V1.0
*/

2、内容注释
每个变量的声明语句单独放到一行,并加上注释说明。每行缩进要保持一致

var currentEntry; // 注释内容
var size;          //注释内容

单行注释与多行注释

// 注释内容
/*
注释内容
*/

文章作者: iitshare
本文地址:http://www.iitshare.com/java-notes-norms.html
版权所有 © 转载时必须以链接形式注明作者和原始出处!

更多

One Response to “java项目开发规范-注释规范”

发表评论