文档约定
1.为那些使用你代码和维护它的人写文档
2.保持注释与代码同步
注释类型
1.使用文档注释来描述程序接口
/**
*A documentation comment
*/
2.使用标准注释来隐藏代码而不是删除
/*
*A standard comment
*/
3.使用单行注释来解释实现细节
//A one-line comment
文档注释
1.在写代码之前描述程序接口
2.对public、protected、package和private 成员进行文档注释
3.对每一个包提供概述
4.对每一个应用或者包的组提供概述，可以在package使用@see标签
注释内容
1.给每一个方法提供概述
2.完整描述每一方法签名
3.包含示例,例如：ateFormat的类的注释
/**
* ...
* If you are formatting multiple numbers, it is
* more efficient to get the format just once so
* the system does not have to fetch the
* information about the local language and
* country conventions multiple times:
* <pre>
* DateFormat df = DateFormat.getDateInstance();
* for (int i = 0; i < a.length; ++i) {
* output.println(df.format(myDate[i]) + "; ");
* }
* </pre>
* To format a number for a different Locale,
* specify the locale in the call to
* <code>getDateInstance</code>:
* <pre>
* DateFormat df;
* df = DateFormat.getDateInstance(Locale.US);
* </pre>
* ...
*/
public abstract class DateFormat extends Format {
...
}
4.对前置、后置、不变条件进行文档注释
5.对已知的缺陷和不足进行文档注释
6.对synchronized同步语法进行文档注释
内部注释
1.只有当内部注释有助于其他人理解你的代码时才添加，所以没用的注释、无关联的注释不要添加
2描述代码为什么那样做，而不是做了什么
3.避免使用行尾的注释，行尾注释只能在很短的注释时使用
4.使用行尾注释解析局部变量声明
int cur = 0; // Index of current pattern element
5.建立并使用一套关键字来标记未确定的情况
// :UNRESOLVED: EBW, 11 July 1999
// This still does not handle the case where
// the input overflows the internal buffer!!
while (everMoreInput) {
...
}
6.在两个case标签中，如果没有break语句分隔这些标签，加入”fall-through”注释
switch (command) {
case FAST_FORWARD:
isFastForward = true;
// Fall through!
case PLAY:
case FORWARD:
isForward = true;
break;
case FAST_REWIND:
isFastRewind = true;
// Fall through!
case REWIND:
isRewind = true;
break;
...
}
7.在嵌套程度高的控制结构中标记结束
for (i...) {
for (j...) {
while (...) {
if (...) {
switch (...) {
...
} // end switch
} // end if
} // end while
} // end for j
} // end for i