java注释（java笔记6）

*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注释参考:

类/接口注释 /** * The <code>String</code> class represents character strings. All * string literals in Java programs, such as <code>"abc"</code>, are * implemented as instances of this class. * (其他描述) * @author Lee Boynton * @author Arthur van Hoff * @author Martin Buchholz * @author Ulf Zibis * @see java.lang.Object#toString() * @see java.lang.StringBuffer * @see java.lang.StringBuilder * @see java.nio.charset.Charset * @since JDK1.0 */ 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; // Default to 0 /** 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; // Note: toffset, ooffset, or len might be near -1>>>1. 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) { // If characters don't match but case may be ignored, // try converting both characters to uppercase. // If the results match, then the comparison scan should // continue. char u1 = Character.toUpperCase(c1); char u2 = Character.toUpperCase(c2); if (u1 == u2) { continue; } // Unfortunately, conversion to uppercase does not work properly // for the Georgian alphabet, which has strange rules about case // conversion. So we need to make one last check before // exiting. if (Character.toLowerCase(u1) == Character.toLowerCase(u2)) { continue; } } return false; } return true; } String(char[] value, boolean share) { // assert share : "unshared not supported"; this.value = value; } char[] val = value; /* avoid getfield opcode */ public boolean contentEquals(CharSequence cs) { if (value.length != cs.length()) return false; // Argument is a StringBuffer, StringBuilder 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; } // Argument is a String if (cs.equals(this)) return true; // Argument is a generic CharSequence 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标签