java注释标签in_Java注释

注释类型

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

方法

不建议使用该方法

注释原则

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

注释准确简洁

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

避免复杂注释

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

TODO List

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

注释形式统一

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

注释与代码同步更新

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

注释就近

保证注释与其描述的代码相邻, 在代码上方或右方(最好上方)进行注释.

注释不要过多

注释必不可少,但也不应过多,注释占程序代码的比例少于20%为宜.注释是对代码的“提示”,而不是文档. 如果代码本来就一目了然就不加注释.

删除无用注释

在代码交付或部署发布之前, 删除临时或无关注释, 避免日后维护中产生混乱.

必加注释之处

典型算法必有注释

代码不明晰处必有注释

在循环/逻辑分支组成的代码中加注释

为他人提供的接口必有注释

在代码修改处加修改标识

附：开发者工具

IDEA: 比较给力的Java IDE,  非常多很赞的功能, 如对Git、Maven的原生支持, 自动代码提示, 自带命令行, 黑色主题, UML类图生成… 而且现在IDEA家族也越来越强, Android开发的Android Studio、IOS的AppCode、C/C++的CLion、Python的PyCharm、PHP的PhpStorm、前端的WebStorm等等, 详细可查看Jet Brains官网.

发表评论

评论已关闭。