俗话说,看别人的代码是件痛苦的事,同样,读自己的代码也是件痛苦的事。几个月前写的喳喳,现在拿出来看,简直一头雾水。这个引用是什么意思?这个方法是干啥的?这个类是干啥的?为什么要这么实现?等等。这个时候要是有清晰明了的注释就简直太爽。所以,为了不让自己浪费太多时间去回想,去猜代码意思。因而不得不养成良好的注释习惯。对我个人而言,命名规范、缩进规范不用强调,但对于注释规范还是很有必要学习一下。为此我选择《华为java编程规范》进行注释规范整理。
1.1 规则
一般情况下,源程序有效注释量必须在30%以上。注释的原则是有利于程序的阅读理解,在该加的地方都加了,注释太多也不要太少,注释语言必须准确,易懂,简洁。
1.2包的注释
包的注释写入一个名为package.html的HTML格式说明文件放入当前路径(为方便javaDoc收集)
示例:com/huawei/relay/com/pavkage.html
1.2.1包的注释内容
简述本包作用、详细描述本包的内容、产品模块名称和版本、公司版权
示例:
<html> <body> <p>为relay 提供通信类,上层业务使用本包的通信类与Sp通信//一句话简述 <p>详细描述。。。。。 <p>MCSC V100R002 Relay <br>(C) 版权所有 2002 -2007 华为技术有限公司 </body> </html>
1.3文件(内)注释
示例:
1.3.1类和接口的注释/* 文件名:LogManager.java 版权:Copyright 2002-2007 描述: MCSC V100R002 Relay 通用日志系统 修改人:张三 修改时间:2002/1/1 修改内容:新增 */
该注释放在package关键字之后,class或interface关键字之前。方便JavaDoc收集。
示例:
1.3.2类属性、共有和保护方法注释。写在类属性,共有和保护方法的上面。package com.huawei.msg.relay.com; /* *LogManager 类集中控制对日志的读写操作 *@author 李四 张三 *@version *@模块版本 */ public class LogManager
示例:
/* 注释内容 */ private String logType; /* *根据日志类型和时间读取日志(一句话功能简述) *分配对应日志类型的logReaer,指定类型,查询事件,条件和反复器缓冲数。读取日志记录,查询条件为null或0时,表示无限制。 *@return buferNum 日志缓冲器记录数 */ public void lorReader(String logType , Date startTime , Date enTime , String userName) { //注释 注释应当与所描述的内容进行同样的缩进 CodeBlock one; //注释 注意将注释与其上面的代码用空行隔开 CodeBlock two; }
1.3.3变量的定义和分支语句块
示例:
//如果 receiveFlag 为真 if(receiveFlag) { program codel; while(...){ program code2; }//end of while(index < MAX_INDEX) }//end of if(...) //指明是if语句结束。 *在程序块结束行右方加注释标记,以表明某程序块的结束。