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标签

标签 作用域 说明
@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 String class represents character strings. All
 * string literals in Java programs, such as "abc", 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 {
    ...
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 构造器注释
    /**
     * 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;
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 方法注释
    /**
     * Returns true if, and only if, {@link #length()} is 0.
     *
     * @return true if {@link #length()} is 0, otherwise
     * false
     *
     * @since 1.6
     */
    public boolean isEmpty() {
        return value.length == 0;
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 字段/属性注释
    /** 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:
     * 
     *      TC_STRING (utf String)
     * 
* The String is written by method DataOutput.writeUTF. * 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];
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 方法内注释
    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;
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78






你可能感兴趣的:(javaSE笔记,注释,代码规范)