Java 注释

Java 注释

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

引

　　程序员圈有一个笑话

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

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

Java三种注释类型

　　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 {@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}
     */

# javadoc 注释标签语法

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

Java代码注释原则

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

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

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 {
    ...
}

• 构造方法注释

    /**
     * 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;
    }

• 方法注释

    /** * 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;
    }

• 字段/属性注释

    /** 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];

• 方法内的注释

    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;
    }

附: 开发者工具

• IDEA: 一款比较给力的Java IDE, 用过都说好(我师兄说:”自从用了IDEA, 写代码越来越有劲儿了”). 有很多很赞的功能, 比如对Git与Maven的支持, 智能的代码提示, 自带命令行工具, 黑色的主题(比较适合zhuangbility)… 但是商业版本比较贵, 不过有社区开源版本; 而且现在IDEA家族现在变得越来越强了, Android Studio就是基于该IntelliJ IDEA的开源版本版本进行Android定制开发的, 而且现在IDEA又出了C/C++版本 CLion, 当年我还在写C/C++的时候听说过这款IDE, 不过没怎么用, 大致浏览了一下, 感觉还是挺酷的.
• Git&GitHub: GitHub作为全球最大同性交友网站就不用多做介绍了, 而Git则算是互联网开发者居家旅行必备吧. 这方面我看过视频, 也看过书, 不过我在这里只推荐一部文档, 虽然Git内容很多, 但是大部分知识感觉是三五年内用不到的, 而这一篇文档却直取要害, 非常实用, 读了很多遍, 原文链接.
• Maven: 在阿里, 开发Java项目要遵守Maven的规范, 我个人也比较喜欢使用Maven构建Java项目, 最起码不用把Jar包拷贝过来拷贝过去了. 不过这方面我也是新手, 因此在这里我只推荐一部还不错的Maven方面的书, Maven实战, 一部国人写的非常棒的实战类书籍, 让我对国人写的技术书籍重拾信心.
• MySQL-Workbench: 一款MySQL的GUI客户端, 在Mac上感觉是用的最爽的一个了, 以前用过几个版本的Navicat, 数据库表一旦大了之后就变得很卡, 而workbench则完全没有问题, 而且灰色的主题也比较护眼.
• ProcessOn: 一个绘图的网址, 可以绘制一些UML图之类的, 上手容易.
• Markdown: 这个就不多说了, 我也是初学者, 好像现在写博客的技术人员都在用, 本篇博客也是我用Markdown写的第一篇博客.
• 再推荐几个JSON查看与编辑的网站:
  
  • qqe2.com, 这个网站对JSON数据的排错提示功能很强大;
  • json.cn, 查看JSON数据非常美观, 支持代码折叠. JSON方面没有发现比较好用的客户端, 希望知道的同学可以推荐几个.

另: 个人感觉自己整理的这些工具还不全, 而且注释的规范还未覆盖到很多地方, 希望看到这篇博客的同学可以给出更多的建议, 我会尽快地把他更新到这篇博客上面.