Java 注释

Java 注释

标签 : Java基础

五月份得知入职阿里云OS, 才开始学Java, 断断续续学习/使用半年, 越来越喜欢这个语言/工具. 后来被拥抱变化之后, 拿到的大部分offer是Java服务端研发; 一路走来, 踩了很多坑, 也有了一点小小的心得, 而且博客已经停更几个月, 今天就以博客形式把他记录下来吧.

2015下半年第一篇博客, 从最基础的Java注释开始:


　　程序员圈有一个笑话

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

为什么写注释?

　　我自己亲身经历:

　　这段时间在微店实习, 第一个接手的项目是将原先北京团队的代码迁移到杭州, 由于底层技术架构的更换, 大部分代码需要重写, 前提是要理解原先的业务逻辑, 但当我在SVN上把代码拉下来, 看到意大利面似的一大坨代码里只有寥寥几行注释时, 整个人都不好了…

　　另一个遇到场景, 有时自己的代码有Bug, 或者需要重构, 此时就需要Review代码, 可是突然发现自己已经很难理解原先逻辑了(很可能这段代码只是你前几天刚刚写的), 因为我们已经很难回到当时状态.

　　还有一个重要的原因就是文档, 往往一个系统被开发出来, 文档要么不全, 要么更新落后, 如果后人要接手这一套系统, 就必须直接阅读源码, 如果此时在代码的关键逻辑之处能够有一两行注释提示, 新人就没有必要绞尽脑汁去猜测当时的设计方案了.

　　后来自己写代码时就尽量写注释提示, 虽然不一定完全按照下面的注释规范, 但会尽量用 最简单的语言把问题阐述清楚, 在逻辑转折之处添加几行说明, 无论是自己还是未来的接手人, 都会对现在的你感激不尽.

注释类型

　　Java提供三种注释方式: 单行注释、多行注释、文档注释.

  • 单行/多行注释

    单行注释与多行注释的作用就不再赘, 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);
        }
*/
  • 文档注释

    　　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 方法 不建议使用该方法

注释原则

下面是我自己看到和用过的注释原则:

  1. 注释准确简洁

    内容简单明了、含义准确, 尽量用最少的语言把问题阐述清楚, 防止注释的多义性,错误的注释不但无益反而有害.

  2. 避免复杂注释

    如果需要用复杂的注释来解释代码, 请检查此代码是否应该重写. 尽一切可能不注释难以理解的代码, 最好选择重构.

  3. TODO List

    为尚未完成的代码添加TODO注释, 提醒自己还需后续完善.

  4. 注释形式统一

    在整个项目中,使用一致的结构样式来构造注释.

  5. 注释与代码同步更新

    边写代码边注释,因为以后很可能没有时间来写注释了(可能在今天看来很明显的东西六周以后或许就不明显了). 通常描述性注释先于代码创建、解释性注释在开发过程中创建、提示性注释在代码完成之后创建. 修改代码的同时修改注释,保证代码与注释同步.

  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的原生支持, 自动代码提示, 自带命令行, 黑色主题, UML类图生成… 而且现在IDEA家族也越来越强, Android开发的Android Studio、IOS的AppCode、C/C++的CLion、Python的PyCharm、PHP的PhpStorm、前端的WebStorm等等, 详细可查看Jet Brains官网.
  • Git&GitHub: Git就不用多做介绍了, 算是开发者居家旅行之必备吧. 这方面的书/视频很多, 但在此我只推荐一部文档: 廖雪峰的Git教程. 虽然Git内容繁多, 但这篇文档却直取要害, 非常实用, 读了很多遍.
  • Maven: Maven方面我也是新手, 在此我只推荐一部还不错的Maven方面的书, Maven实战, 一部国人写的实战类书籍.
  • SQLPro for MySQL: 一款MySQL-GUI客户端, 用过MySQL-WorkBench、Navicat、Sequel Pro, 但最后还是选择的SQLPro for MySQL.
  • ProcessOn: 免费绘图网站, UML、流程图、网络拓扑… 上手容易.
  • Markdown: 这方面我也是初学者, 推荐两个客户端Cmd Markdown、MWeb.
  • JSON查看&编辑

    这方面除了TextLab没有发现其他好用的客户端, 只能推荐几个网站:

    • qqe2.com: 对JSON数据排错提示功能很强大;
    • json.cn, 查看JSON数据非常美观, 支持代码折叠.
  • RegExRx

    Mac上非常好用的正则表达式匹配引擎, 用于测试正则表达式书写的正确与否.

  • iTerm2

    忘掉Mac自带的终端吧, iTerm你值得拥有.

  • Alfred

    最后, 推荐Mac效率神器Alfred, 推荐博客: 从零开始学习 Alfred（上）：基础功能及设置, 其他功能还在探索.

在此只推荐了我所知道和常用一些小工具, 欢迎同学补充.

时间： 2024-08-03 03:11:58

Java 注释的相关文章

java注释 命名 数据类型 基本类型转换 位运算符 逻辑运算符 三目运算符

一.java注释 1.单行注释  //注释内容 2.多行注释 /*注释内容*/ 3.文档注释(可用javadoc工具生成api文档,不过我还没试过)/**文档注释*/,文档注释可以在使用的时候看见注释. 文档注释常用的标记 @auther作者 @version版本 @deprecated 不推荐使用 @param 本放的参数 @return 返回值 @throws异常,同@exception 二.java的命名 1.项目名 字母全部小写 2.包名 全部小写 3.类名 首字母大写加驼峰 4.方法名

JAVA注释的另一种神奇用法

每个JAVA程序员在写程序的时候一定都会用到注释,本篇博客不是讲怎么定义注释,而是说明注释神奇的一种写法. 1 /** 2 * 这是一个测试类 3 */ 4 public class Test { 5 /** 6 * 程序的入口 7 */ 8 public static void main(String[] args) { 9 new Test(); 10 } 11 } 以上是两个普通的多行注释,在IDEA的环境下,选中方法或者类名,按住Ctrl+Q(Eclipse开发环境下直接按住Ctrl然后

java注释规范

前言: 现在java的出产地sun公司并没有定义一个java注释规范,注释规范目前是每个公司自己有自己的一套规范,主要是为了团队之间的协作. 1.基本规则 1.注释应该使代码更加清晰易懂 2.注释要简洁明了,只要提供能够明确理解程序必要的信息就可以了.如果注释太复杂会影响程序整洁度和阅读感. 3.注释不仅描述程序作了什么,还要描述为什么这样做以及约束. 4.对于一般的getter和setter方法不用注释. 5.类.接口.构造函数.方法.全局变量必须添加注释.字段属性可以选择添加简单注释. 6.

Java注释用处

1.Java注释: 1 import cn.lonecloud.Doc; 2 3 /** 4 * Created by lonecloud on 2017/8/17. 5 * 测试注释类型 {@link Doc#test() 测试这个标签作用} 6 * @author lonecloud 7 * @see cn.lonecloud.Doc 8 * @version 1.0 9 * 10 */ 11 @Deprecated 12 public class JavaDocDemo { 13 /**

Java注释总结

Java注释总结 注释风格设置方法: WindowàpreferencesàJavaàCode StyleàCode TemplatesàComments javadoc注释 @author      类作者 @version     类版本 @see       转向参考 @param      方法参数说明 @return      方法返回值说明 @exception    方法异常说明     描述内容可以使用html标签 类中: 方法中: 注释快捷键 对类做注释在类的上一行打出"/**

Java注释分类

Java注释分类 1.单行注释    //打印结果    System.out.println("结果是:"+result); 2.多行注释    /**     * @author youhaidong     * for循环语句     */     for(int i=0;i<10;i++)     {         System.out.println(i);     } 3.文档注释    /**     * Description:     * @Author:yo

Java注释Annotation

 Java注释Annotation 从JDK 5开始,Java增加了对元数据(MetaData)的支持,也就是Annotation(注释).Annotation提供了一种为程序元素设置元数据的方法,程序元素包括修饰包.类.构造器.方法.成员变量.参数.局部变量,从某些方面来看,Annotation就想修饰符一样,可用于程序元素的声明,这些信息被存储在Annotation的"name = value"对中. 需要注意的是, Annotation是一个接口,程序可以通过反射来获取指定程

myeclipse自定义java注释

myeclipse自定义java注释: Window->Preference->Java->Code Style->Code Template 然后展开Comments节点就是所有需设置注释的元素 ----------------- 文件 (Files) 注释标签: /** * @Project : ${project_name} * @Title : ${file_name} * @Package ${package_name} * @Description : ${todo}

Java注释规范整理

在软件开发的过程中总是强调注释的规范,但是没有一个具体的标准进行说明,通常都是在代码编写规范中简单的描述几句,不能作为一个代码注释检查的标准和依据,做什么都要有一个依据吗:),现在我特整理了一个<Java的注释规范>,内容来自网络.书籍和自己的实际积累. JAVA注释规范 版本/状态 作者 版本日期 1.0 ghc 2008-07-02 一.背景 1.当我们第一次接触某段代码,但又被要求在极短的时间内有效地分析这段代码,我们需要什么样的注释信息? 2.怎么样避免我们的注释冗长而且凌乱不堪呢?