代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范,供大家参考下。

原则

1、注释形式统一

在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范。

2、注释内容准确简洁

内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。

注释条件

1、基本注释(必须加)

(a)    类(接口)的注释

(b)    构造函数的注释

(c)     方法的注释

(d)    全局变量的注释

(e)    字段/属性的注释

备注:简单的代码做简单注释,注释内容不大于10个字即可,另外,持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。

2、特殊必加注释(必须加)

(a)    典型算法必须有注释。

(b)    在代码不明晰处必须有注释。

(c)     在代码修改处加上修改标识的注释。

(d)    在循环和逻辑分支组成的代码中加注释。

(e)    为他人提供的接口必须加详细注释。

备注:此类注释格式暂无举例。具体的注释格式自行定义,要求注释内容准确简洁。

注释格式

1、单行(single-line)注释:“//……”

2、块(block)注释:“/*……*/”

3、文档注释:“/**……*/”

4、javadoc 注释标签语法

@author   对类的说明 标明开发该类模块的作者

@version   对类的说明 标明该类模块的版本

@see     对类、属性、方法的说明 参考转向,也就是相关主题

@param    对方法的说明 对方法中某参数的说明

@return   对方法的说明 对方法返回值的说明

@exception  对方法的说明 对方法可能抛出的异常进行说明

参考举例

1.   类(接口)注释

例如:

/**

* 类的描述

@author Administrator

* @Time 2012-11-2014:49:01

*

*/

public classTest extends Button
{

……

}

2.   构造方法注释

例如:

public class Test extends Button
{

/**

* 构造方法 的描述

@param name

*       按钮的上显示的文字

*/

public Test(String name){

……

}

}

3.   方法注释

例如

public class Test extends Button
{

/**

* 为按钮添加颜色

*@param color

按钮的颜色

*@return

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

* @author Administrator

* @Time2012-11-20 15:02:29

*/

public voidaddColor(String
color){

……

}

}

4.   全局变量注释

例如:

public final class String

implements java.io.Serializable,
Comparable<String>,CharSequence

{

/** The value is used for characterstorage. */

private final char value[];

/** The offset is the first index of thestorage that is used. */

private final int offset;

/** The count is the number of charactersin the String. */

private final int count;

/** Cache the hash code for the string */

private int hash; //
Default to 0

……

}

5.   字段/属性注释

例如:

public class EmailBody implements Serializable{

private String id;

private String senderName;//发送人姓名

private String title;//不能超过120个中文字符

private String content;//邮件正文

private String attach;//附件,如果有的话

private String totalCount;//总发送人数

private String successCount;//成功发送的人数

private Integer isDelete;//0不删除 1删除

private Date createTime;//目前不支持定时 所以创建后即刻发送

privateSet<EmailList> EmailList;

……

}

其实规范是自己订的,只要团队中大家都统一遵守,统一规范,就会取得好的效果,希望对平时不加注释的朋友有点帮助。

java代码注释规范的更多相关文章

  1. [转]java代码注释规范

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二期开发中使用的代码注释规范 ...

  2. JAVA 代码开发规范

    一.开发工具规范: 1. 开发工具经项目负责人调试后统一确定. 2. 开发工具一经确定不允许集成任何非统一插件,若有需要,经项目负责人同意后统一为 项目组成员添加. 3. 开发工具的编码格式不允许修改 ...

  3. Java代码格式化规范实践总结

    目标说明 统一良好的代码格式规范可以有效提升开发团队之间的「协作效率」,如果不同的开发团队或者开发人员采用不同的代码格式规范,那么每次Format代码都会导致大量的变化,在Code Review及Me ...

  4. PHPDocument 代码注释规范总结

    PHPDocument 代码注释规范 1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通 ...

  5. eclipse中添加Java代码注释模板

    eclipse中添加Java代码注释模板 1.Window->Preference->Java->Code Style->Code Template,进入注释编辑界面 2.文件 ...

  6. 代码注释规范-IDEA 配置 Java 类方法注释模板

    1. 引言     团队开发时,业务模块分配的越清晰,代码注释管理越完善,越有利于后面维护,后面再管理也方便不少.另外也起着"文字砖"的作用,你懂的.注释不需要很详细,把代码块方法 ...

  7. Eclipse和MyEclipse 手动设置 Java代码 注释模板

    一.目的 1.  为什么需要注释规范? 注释规范对于程序员而言尤为重要,有以下几个原因: 一个软件的生命周期中,80%的花费在于维护. 几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维 ...

  8. Java代码编写规范(不是标准规范,自行整理,无须纠结)

    最近回过头来给以前的项目增加功能,发现之前写的注释非常不全,代码也非常的不整洁,有些地方写的''窝七八烂的,看着很不舒服:又恰好经理最近也经常跟我提起代码规范,我们就讨论了一下代码规范的重要性和必要性 ...

  9. (转)Java代码书写规范

    0. 安装阿里代码规范的eclipse插件 https://www.cnblogs.com/caer/p/7753522.html 1.基本原则 强制性原则:     1.字符串的拼加操作,必须使用S ...

随机推荐

  1. spring中各jar功能及jar包之间的依赖关系

    (1) spring-core.jar 这个jar文件包含Spring框架基本的核心工具类,Spring其它组件要都要使用到这个包里的类,是其它组件的基本核心,当然你也可以在自己的应用系统中使用这些工 ...

  2. Swing应用开发实战系列之五:后台日志信息前台监控器

    作为一个程序设计人员,我们深知日志的重要性,对于日志的监控,我们通常不外乎采用以下两种方式:日志文件方式和后台打印方式,常规情况下,这两种日志监控方式完全可以满足我们对日志监控的需要.但是,当我们用S ...

  3. 如何在centos上安装epel源

    一.EPEL是什么? EPEL (Extra Packages for Enterprise Linux,企业版Linux的额外软件包) 是Fedora小组维护的一个软件仓库项目,为RHEL/Cent ...

  4. 1---------java调用NLPIR(ICTCLAS2016)实现分词功能

    备注:win7 64位系统,netbeans编程 NLPIR分词系统,前身是2000年发布的ICTCLAS,2009年更为现名.张华平博士打造. 实现步骤: 1.在Netbeans中,文件→新建项目→ ...

  5. 【学习笔记】Wireshark的用法

    计算机网络课上,需要我们灵活运用网络协议分析仪wireshark,最近一直在看,感觉有点难,并不是软件本身操作难,而是看懂一大群包的含义难,这个难主要也因为它是全英文的~~.. 好了,大致总结一下,基 ...

  6. 修改/etc/profile文件

    通常情况下,/etc/profile文件是只读的,直接用vi或gedit打开修改后是无法保存的.要修改profile,需要取得root权限,(使用gedit编辑)应该如下: $sudo gedit / ...

  7. SCCM 客户端的修复

    1. Stopping the SMS Agent Host service (net stop ccmexec) 2. Stopping the WMI service (net stop winm ...

  8. AngularJS 拦截器

    在需要进行身份验证时,在请求发送给服务器之前或者从服务器返回时对其进行拦截,是比较好的实现手段. 例如,对于身份验证,如果服务器返回401状态码,将用户重定向到登录页面. AngularJS通过拦截器 ...

  9. 学习OpenStack之 (2):Cinder LVM 配置

    0.背景 OpenStack 中的实例是不能持久化的,cinder服务重启,实例消失.如果需要挂载 volume,需要在 volume 中实现持久化.Cinder提供持久的块存储,目前仅供给虚拟机挂载 ...

  10. Andorid 6连接Libreswan L2TP VPN

    手机升级到Android 6以后,以前正常使用的L2TP VPN却无法连接了.服务器端日志: "vpnpsk"[119] 114.249.245.192 #240: no acce ...