*1.程序员圈有一个笑话 最讨厌在写代码的时候写注释, 最讨厌别人的代码里面不写注释.
*2.良好的编码习惯 代码注释规范化
*3.代码注释 提高团队开发合作效率,提高程序代码的可阅读性,提高程序代码的可维护性。
*4.注释内容 要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。
*5.注释种类
1.单行注释(line comment) 用 // 表示,快捷键:Ctrl+/ 撤消:Ctrl+/
编译器看到//会忽略该行//后的所文本
2.多行注释,又叫块注释 (block comment) 用/* */表示,快捷键:Ctrl+Shift+/ 撤消:Ctrl+Shift+\
编译器看到/*时会搜索接下来的*/,忽略掉/**/之间的文本。
3.文档注释 用/** */表示,快捷键:Alt+Shift+J
是java特有的注释,其中注释内容可以被JDK提供的工具 javadoc 所解析,生成一套以网页文件形式体现的该程序的说明文档API。
*6.文档注释 (编写软件说明书)
1. 需要使用sum给我们提供的javadoc工具生成一个html的说明文档。
2. 只能抽取public的属性或者方法内容。
格式:
Javadoc –d 指定存储文档的路径 -version –author(可选) 目标文件
*7.Javadoc标签
Javadoc标签
标签 作用域 说明
@author 类 标明开发该类模块作者 @version 类 标明该类模块的版本 @see 类, 属性, 方法 参考转向(相关主题) @param 方法 对方法中某参数的说明 @return 方法 对方法返回值的说明 @exception 方法 抛出的异常类型 @throws 方法 与@exception相同 @deprecated 方法 不建议使用该方法
*8.常见注释规范:
1、基本注释(必须加)
(a) 类(接口)的注释 文档注释 版本,作者,时间,说明
(b) 构造函数的注释 文档注释
(c) 方法的注释 文档注释
(d) 全局变量的注释 多行注释
(e) 字段/属性的注释 单行注释
2、特殊必加注释(必须加)
(a) 典型算法必须有注释。
(b) 在代码不明晰处必须有注释。
(c) 在代码修改处加上修改标识的注释。
(d) 在循环和逻辑分支组成的代码中加注释。
(e) 为他人提供的接口必须加详细注释。
*9. 注释的嵌套
1.
单行注释可以在单行注释里面。
2.多行注释不能嵌套在多行注释里面。
*10. 注释的调试作用:
1. 可以作为初学者的调试方式。
2. 可以帮组初学者确定代码的错误之处。
*11.代码规范 checkStyle + codetemplates + formatter
*12.JDK注释参考:
类/接口注释
public final class String
implements java.io.Serializable, Comparable<String>, CharSequence {
...
}
1234567891011121314151617181920
构造器注释
/**
* Initializes a newly created {@code String} object so
that it represents
*
the same sequence
of characters as the argument;
in other
words,
the
* newly created
string is a
copy of the argument
string. Unless an
* explicit
copy of {@code original}
is needed, use
of this constructor
is
* unnecessary
since Strings are immutable.
*
* @param original
* A {@code String}
*/
public String(String original) {
this.value = original.value;
this.hash = original.hash;
}
1234567891011121314
方法注释
/**
* Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>.
*
* @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise
* <tt>false</tt>
*
* @since 1.6
*/
public boolean isEmpty() {
return value.length ==
0;
}
1234567891011
字段/属性注释
/** The value is used for character storage. */
private final char value[];
/** Cache the hash code for the string */
private int hash;
/** use serialVersionUID from JDK 1.0.2 for interoperability */
private static final long serialVersionUID = -
6849794470754667710L;
/**
* Class String is special cased within the Serialization Stream Protocol.
*
* A String instance is written initially into an ObjectOutputStream in the
* following format:
* <pre>
* <code>TC_STRING</code> (utf String)
* </pre>
* The String is written by method <code>DataOutput.writeUTF</code>.
* A new handle is generated to refer to all future references to the
* string instance within the stream.
*/
private static final ObjectStreamField[] serialPersistentFields =
new ObjectStreamField[
0];
1234567891011121314151617181920212223
方法内注释
public boolean
regionMatches(boolean ignoreCase,
int toffset,
String other,
int ooffset,
int len) {
char ta[] =
value;
int to = toffset;
char pa[] = other.
value;
int po = ooffset;
if ((ooffset <
0) || (toffset <
0)
|| (toffset > (
long)
value.length - len)
|| (ooffset > (
long)other.
value.length - len)) {
return false;
}
while (len-- >
0) {
char c1 = ta[to++];
char c2 = pa[po++];
if (c1 == c2) {
continue;
}
if (ignoreCase) {
char u1 = Character.toUpperCase(c1);
char u2 = Character.toUpperCase(c2);
if (u1 == u2) {
continue;
}
if (Character.toLowerCase(u1) == Character.toLowerCase(u2)) {
continue;
}
}
return false;
}
return true;
}
String(
char[]
value, boolean share) {
this.
value =
value;
}
char[] val =
value;
public boolean
contentEquals(CharSequence cs) {
if (
value.length != cs.length())
return false;
if (cs instanceof AbstractStringBuilder) {
char v1[] =
value;
char v2[] = ((AbstractStringBuilder) cs).getValue();
int i =
0;
int n =
value.length;
while (n-- !=
0) {
if (v1[i] != v2[i])
return false;
i++;
}
return true;
}
if (cs.equals(
this))
return true;
char v1[] =
value;
int i =
0;
int n =
value.length;
while (n-- !=
0) {
if (v1[i] != cs.charAt(i))
return false;
i++;
}
return true;
}
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
Javadoc标签