java代码注释规范-----转载-----http://blog.csdn.net/shiyuezhong/article/details/8205281/ 

  1 代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范，供大家参考下。
  2 
  3 原则：
  4 1、注释形式统一
  5 
  6 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同，按照这份规范写代码，不要试图在既成的规范系统中引入新的规范。
  7 
  8 2、注释内容准确简洁
  9 
 10 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 
 19 
 20 
 21 
 22 
 23 
 24 
 25 
 26 注释条件：
 27 
 28 1、基本注释（必须加）
 29 
 30 (a)    类（接口）的注释
 31 
 32 (b)    构造函数的注释
 33 
 34 (c)     方法的注释
 35 
 36 (d)    全局变量的注释
 37 
 38 (e)    字段/属性的注释
 39 
 40  备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。
 41 
 42 2、特殊必加注释（必须加）
 43 
 44 (a)    典型算法必须有注释。
 45 
 46 (b)    在代码不明晰处必须有注释。
 47 
 48 (c)     在代码修改处加上修改标识的注释。
 49 
 50 (d)    在循环和逻辑分支组成的代码中加注释。
 51 
 52 (e)    为他人提供的接口必须加详细注释。
 53 
 54  备注：此类注释格式暂无举例。具体的注释格式自行定义，要求注释内容准确简洁。
 55 
 56 
 57 注释格式：
 58 
 59 1、单行(single-line)注释：“//……”
 60 
 61 2、块(block)注释：“/*……*/”
 62 
 63 3、文档注释：“/**……*/”
 64 
 65 4、javadoc 注释标签语法
 66 
 67 @author   对类的说明 标明开发该类模块的作者
 68 
 69 @version   对类的说明 标明该类模块的版本
 70 
 71 @see     对类、属性、方法的说明 参考转向，也就是相关主题
 72 
 73 @param    对方法的说明 对方法中某参数的说明
 74 
 75 @return   对方法的说明 对方法返回值的说明
 76 
 77 @exception  对方法的说明 对方法可能抛出的异常进行说明
 78 
 79 
 80 参考举例：
 81 
 82 1.   类（接口）注释
 83 
 84 例如：
 85 
 86 /**
 87 
 88 * 类的描述
 89 
 90 * @author Administrator
 91 
 92 * @Time 2012-11-2014:49:01
 93 
 94 *
 95 
 96 */
 97 
 98 public classTest extends Button {
 99 
100   ……
101 
102 }
103 
104 2.   构造方法注释
105 
106 例如:
107 
108 public class Test extends Button {
109 
110   /**
111 
112    * 构造方法 的描述
113 
114    * @param name
115 
116    *       按钮的上显示的文字
117 
118    */
119 
120   public Test(String name){
121 
122      ……
123 
124   }
125 
126 }
127 
128 3.   方法注释
129 
130 例如
131 
132 public class Test extends Button {
133 
134   /**
135 
136    * 为按钮添加颜色
137 
138    *@param color
139 
140          按钮的颜色
141 
142 *@return
143 
144 *@exception  (方法有异常的话加)
145 
146 * @author Administrator
147 
148 * @Time2012-11-20 15:02:29
149 
150 
151    */
152 
153   public voidaddColor(String color){
154 
155      ……
156 
157   }
158 
159 }
160 
161 4.   全局变量注释
162 
163 例如：
164 
165 public final class String
166 
167    implements java.io.Serializable, Comparable<String>,CharSequence
168 
169 {
170 
171    /** The value is used for characterstorage. */
172 
173    private final char value[];
174 
175    /** The offset is the first index of thestorage that is used. */
176 
177    private final int offset;
178 
179    /** The count is the number of charactersin the String. */
180 
181    private final int count;
182 
183    /** Cache the hash code for the string */
184 
185 private int hash; // Default to 0
186 
187 ……
188 
189 }
190 
191 5.   字段/属性注释
192 
193 例如：
194 
195 public class EmailBody implements Serializable{
196 
197    private String id;
198 
199    private String senderName;//发送人姓名
200 
201    private String title;//不能超过120个中文字符
202 
203    private String content;//邮件正文
204 
205    private String attach;//附件，如果有的话
206 
207    private String totalCount;//总发送人数
208 
209    private String successCount;//成功发送的人数
210 
211    private Integer isDelete;//0不删除 1删除
212 
213    private Date createTime;//目前不支持定时 所以创建后即刻发送
214 
215    privateSet<EmailList> EmailList;
216 
217 ……
218 
219 }
220 
221 其实规范是自己订的，只要团队中大家都统一遵守，统一规范，就会取得好的效果，希望对平时不加注释的朋友有点帮助。

 

posted @ 2016-09-23 08:28  火山林风  阅读(350)  评论(0)    收藏  举报