Java 注释

页面导航:首页 > 软件编程 > Java编程 > Java 注释

Java 注释

来源: 作者: 时间:2016-01-21 09:39 【

Java 注释 五月份得知入职YunOS, 开始学习Java, 断断续续学习和使用Java将近半年, 越来越喜欢这个工具, 因此后来被阿里拥抱变化之后, 拿到的的所有的offer都是Java研发; 一路走来, 踩了很多

 

Java 注释

  五月份得知入职YunOS, 开始学习Java, 断断续续学习和使用Java将近半年, 越来越喜欢这个工具, 因此后来被阿里拥抱变化之后, 拿到的的所有的offer都是Java研发; 一路走来, 踩了很多坑, 也有了一点小小的心得, 那就用博客的形式把他记录下来吧…
  写的第一篇Java的博客, 就从最基础的Java注释开始!


  程序员圈有一个笑话

最讨厌在写代码的时候写注释, 最讨厌别人的代码里面不写注释

那为啥要写注释呢?
  我就以自己的亲身经历和理解开始阐述吧:
  这段时间在微店实习, 最开始干的事情就是将原来北京团队的代码迁移到杭州, 由于更换了技术架构, 因此很多代码都需要重写. 但是重写的首先要理解原先的业务逻辑, 当我在SVN(对, 你没有看错, 就是SVN -_-!!)上把代码拉下来, 看到几千行代码里面只有寥寥几行注释时, 我愣了…
  另一个我经常遇到的事情, 有的时候自己写的代码有Bug, 或者可能需要重构, 这时需要review自己的代码, 可是突然发现自己已经很难理解原有的思路, 甚至这段代码可能就是昨天才刚刚写过的, 但是已经很难回到当时写代码的状态了.
  还有一个重要的原因就是代码即文档, 有些时候, 文档的更新速度相对落后, 在这种情况下, 我们解决问题只能直接看代码, 如果一个人的代码写的规范, 模块划分合理, 注释详尽清晰, 其实完全可以起到文档的作用.
  因此后来在自己写代码的时候就强迫自己写注释, 虽然并未按照下面介绍的注释规范, 但是我尽量用最简单的语言把问题阐述清楚, 在代码看起来难懂的地方加上清晰的注释, 这样后来再看代码的时候(无论是自己还是代码的接收人)就没有必要一行一行的跟踪代码了.


三种注释类型

  Java提供三种注释: 单行注释, 多行注释, 文档注释.
1.单行/多行注释
  单行注释与多行注释的作用与用法就不再赘述了, IDEA快捷键分别如下:
   command+/: 以//快速注释一行或多行 :

//        Integer[] array = new Integer[10];
//        for (int i = 0; i < array.length; ++i){
//            array[i] = new Integer(i);
//        }

  command+option+/: 以/**/快速注释一行或多行

/*
        Integer[] array = new Integer[10];
        for (int i = 0; i < array.length; ++i){
            array[i] = new Integer(i);
        }
*/

2.文档注释
  Java语言提供了一种功能非常强大的注释形式: 文档注释. 如果编写Java源代码时添加了合适的文档注释, 然后通过JDK提供的javadoc工具就可以直接将代码里的注释提取成一份的API文档. 其注释形式为/** */

    /**
     * Initializes a newly created [email protected] 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 [email protected] original} is needed, use of this constructor is
     * unnecessary since Strings are immutable.
     *
     * @param  original
     *         A [email protected] String}
     */

# javadoc 注释标签语法

标签 作用域 说明
@author 标明开发该类模块作者
@version 标明该类模块的版本
@see 类, 属性, 方法 参考转向(相关主题)
@param 方法 对方法中某参数的说明
@return 方法 对方法返回值的说明
@exception 方法 抛出的异常类型
@throws 方法 [email protected]
@deprecated 方法 不建议使用该方法

Java代码注释原则

下面是我从网上看到和自己总结的代码注释原则,

1. 注释准确简洁(最重要)
  内容要简单明了、含义准确, 尽量用最少的语言把问题阐述清楚, 防止注释的多义性,错误的注释不但无益反而有害.
2. 避免复杂的注释
  如果需要用复杂的注释来解释复杂的代码,请检查此代码是否应该重写。尽一切可能不注释难以理解的代码,而应该重写它.
3. TODO List
  为尚未完成的代码添加TODO注释, 提醒自己这段代码还需要后续完善.
4. 注释形式统一
  在整个项目中,使用一致的结构样式来构造注释.
5. 注释与代码同步更新
  在写代码之前或边写代码边注释,因为以后很可能没有时间来写注释了(如果有机会review已写的代码,可能在今天看来很明显的东西六周以后或许就不明显了)。通常描述性注释先于代码创建,解释性注释在开发过程中创建,提示性注释在代码完成之后创建。修改代码的同时修改相应的注释,以保证代码与注释的同步.
6. 注释就近原则
  保证注释与其描述的代码相邻, 在代码上方或右方(最好上方)进行注释.
7. 注释不要过多
  注释必不可少,但也不应过多,注释占程序代码的比例达到20%左右为宜。注释是对代码的“提示”,而不是文档,如果代码本来就是清楚、一目了然就不加注释,而且注释的花样要少。
8. 删除无用注释
  在代码交付或部署发布之前,必须删掉临时或无关的注释,以避免在日后的维护工作中产生混乱。
9. 必加注释之处
  - 典型算法必须有注释。
  - 在代码不明晰处必须有注释。
  - 在循环和逻辑分支组成的代码中加注释。
  - 为他人提供的接口必须加详细注释。
  - 在代码修改处加上修改标识的注释


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, CharSequence {
    ...
}
构造方法注释
    /**
     * Initializes a newly created [email protected] 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 [email protected] original} is needed, use of this constructor is
     * unnecessary since Strings are immutable.
     *
     * @param  original
     *         A [email protected] String}
     */
    public String(String original) {
        this.value = original.value;
        this.hash = original.hash;
    }
方法注释
    /**
     * Returns true if, and only if, [email protected] #length()} is 0.
     *
     * @return true if [email protected] #length()} is 0, otherwise
     * false
     *
     * @since 1.6
     */
    public boolean isEmpty() {
        return value.length == 0;
    }
字段/属性注释
    /** 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]; 方法内的注释
    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;
    }
 
Tags:

相关文章

    文章评论

    最 近 更 新
    热 点 排 行
    Js与CSS工具
    代码转换工具
    
    <