Java中注释的规范&规则

最新推荐文章于 2024-08-16 16:40:12 发布

上穷青天揽星辰

最新推荐文章于 2024-08-16 16:40:12 发布

阅读量7.1k

点赞数 4

分类专栏： Java基础知识文章标签： Java Java入门 Java语法 Java基础

本文链接：https://blog.csdn.net/InjoyMario/article/details/95043728

版权

Java基础知识专栏收录该内容

5 篇文章 2 订阅

订阅专栏

为什么写注释？

提高代码可读性；
使程序条理清晰；
方便后期代码维护；
方便程序员间的交流沟通；
生成帮助文档。

——

Java注释的方法有三种：

单行注释：
单行注释，以//开头，//后的内容都是注释，直到这一行的行尾结束。
多行注释：
以/*星号开头，以*/结束，可以有多行。可以使用多行注释作为行内注释，但多行注释不能嵌套使用。
Javadoc注释：
以/**开头，以*/结束，如果有多行，每行通常以*开头
文档注释允许把关于程序的信息嵌入到程序内部，开发者可以用Javadoc工具提取这些信息，并把它们放在HTML文件中，形成帮助文档（后期写项目时，可以生成项目的API）
操作：/** + Enter

——

Java注释具体使用细节：

类、类属性、类方法接口
必须注释且使用Javadoc注释。需要标明，创建者，创建时间，版本，以及该类的作用。如下所示:

package indi.mario.learn.demo;
/*** @author: mario
* @date: 19-07-08
* @version: 1.0.0
* @deion: 生成Jpg工具类
*/
public class JpgUtils {}

原因：
在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释：在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
方法
所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做了什么事情，实现了什么功能。如下所示：

/** * 生成Jpg文件
* @param htmlContent 待生成Jpg的 html内容
* @param file 生成Jpg文件地址
* @see JpgUtils#getFontPath()
* @return true 生成成功 false 生成失败
*/
public static boolean generateJpg(String htmlContent,File file){ … return result; }

说明：对子类的实现要求或者调用的注意事项，请一并说明。
方法内部单行注释，，在被注释语句上方另起一行，使用//注释。方法内容多行注释使用/* */注释，注意与代码对齐。
常量
对常量，我们需要使用多行注释，进行标明该常量的用途，如下所示:

/*** @author: mario
* @date: 19-07-08
* @version: 0.0.1
* @deion:
*/public class StatusConsts {
    /**
    * 博客地址
    */
    public static final String BLOG=“https://blog.csdn.net/InjoyMario”;
}
关键算法
在关键算法上，添加注释并且按照顺序依次标明，写明白该方法为什么这么做。如下所示:

/** * 应用场景:
* 1. 在windows下,使用Thread.currentThread()获取路径时,出现空对象，导致不能使用
* 2. 在linux下,使用JpgUtils.class获取路径为null,
* 获取字体路径
* @return 返回字体路径
*/
private static String getFontPath(){
String path="";
// 1. ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
URL url = (classLoader==null)?null:classLoader.getResource("/");
String threadCurrentPath = (url==null)?"":url.getPath();
// 2. 如果线程获取为null,则使用当前JpgUtils.class加载路径 if(threadCurrentPath==null||"".equals(threadCurrentPath)){
path = JpgUtils.class.getClass().getResource("/").getPath();
}
// 3. 拼接字体路径
StringBuffer stringBuffer = new StringBuffer(path); stringBuffer.append("/fonts/SIMKAI.TTF"); path = stringBuffer.toString(); return path;
}

——

添加注释时的一点建议

类中，接口等必须有创建时间、创建人、版本号、描述等注释。
注释不是越多越好，比如：get/set方法就不需要写注释。更不需要每一行都写注释。
注释需要写的简明易懂。特别是方法的参数，以及返回值。
每一次修改时，相应的注释也应进行同步更新。
在类，接口，方法中，应该都使用/** */Javadoc注释。因为这样调用者就不需要进入方法内部才知道方法的用处。提高编码效率。
方法代码中如果有顺序之分，最好将代码也加上序号，如1，2，3等。
所有的枚举类型字段都必须添加注释，说明每个数据项的用途。
与其用半吊子英文解释，有的时候不如用中文注释说明清楚。
代码如果修改时，注释也要相应修改，尤其是参数、返回值、异常、核心逻辑等的修改。
谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果不用，则删除。
如果注释包含多段内容，段与段之间需要用 <p> 分隔，空行是没用的
为了避免一行过长影响阅读效果，务必将每行的长度限制在80个字符以内.
使用 <code>关键字</code> 来强调关键字，建议强调的内容有：java关键字、包名、类名、方法名、接口名、字段名、参数名
注释要求有二：1.要能反映设计思想和代码逻辑；2.能够描述业务含义
好的命名、代码结构是自解释的。
英文注释避免拉丁风格的缩写。比如使用also knwon as而不是aka，使用that is或to be specific而不是i.e.，使用for example而不是e.g.，使用in other words或namely而不是viz.
特殊注释标记：清注明标记人和标记时间。注意及时处理这些标记，通过标记扫描，经常清理这些标记。线上故障有时候就源于这些标记：
（1）待办事宜（TODO）：（标记人，标记时间，[预计处理时间]）
表示需要实现，但目前还没有实现的功能。这实际上是一个Javadoc的标签。目前Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为他是一个Javadoc标签）
（2）错误，不能工作（FIXME）：（标记人，标记时间，[预计处理时间]）
在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

——

Javadoc注释标签语法：

标签	作用域	说明
`@author`	文件、类、属性、方法	标明开发该类模块的作者，多个作者使用多个@author标签标识，java doc中显示按输入时间顺序罗列。
`@version`	文件、类、方法	标识注释对象的版本号
`@see`	类，属性，方法	参考转向（相关主题）
`@param`	方法	对方法中某参数的说明
`@return`	方法	对方法返回值的说明
`@exception`	方法	方法抛出的异常类型
`@throws`	方法	方法抛出的异常类型说明
`@deprecated`	文件、类、方法	说明对象过期，应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API
`@link`	类、方法	链接到一个目标，用法类似@see，区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。例如{@link …}
`@since JDK版本`	文件、类	用于标识编译该文件所需要的JDK环境。

Java注释的使用顺序

@author (classes and interfaces only, required)
@version (classes and interfaces only, required. See footnote 1)
@param (methods and constructors only)
@return (methods only)
@exception (@throws is a synonym added in Javadoc 1.2)
@see
@since
@serial (or @serialField or @serialData)
@deprecated (see How and When To Deprecate APIs)

多个@author标记，应该按照时间顺序排列，即原作者应该排在第一个位置
多个@param标记，应该按照参数定义的顺序排列
多个@exception（或是@thrown）应该按照异常的字母顺序排列
多个@see标记，应该按照注释的逻辑顺序排列，即从最近的到最远的，从最具体的到最一般的

特别声明：

Javadoc针对public类生成注释文档
标记部分跟在描述部分之后，且前面必须有一个空行间隔
Javadoc只能在public、protected修饰的方法或者属性之上
如果方法有参数，@param必须包含，而且每个对应一个参数
如果方法有返回值，@return必须包含
Javadoc注释的格式化：前导*号和HTML标签
Javadoc注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。
如果源文件中有用到@version,@author标记，则在执行Javadoc命令时，要加-version -author
javadoc -version -author -d doc *.java
（其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）
文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。

——

@see:
    注释中，为更好描述，需要引用和参考其他代码，为更好阅读体验，Javadoc支持链接跳转，需要用到@see
    完整的用法：
         @see package.class#member
    具体用法：

如果指向在当前类中，可以只写#号后面的
如果指向在当前包中，可以省略包名
如果指向在当前项目其它包中，需要指向全路径

@link与@see的小区别：
@see必须顶头写，而@link可以随意放，否则@see会失去效用。
——

注释的抽取

假设HTML文件将被存放在目录docDirectory下。执行以下步骤：

切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录(如果存在overview.html文件的话，这也是它所在目录)。
如果是一个包，应该运行命令：

javadoc -d docDirectory nameOfPackage

或对于多个包生成文档，则运行：

javadoc -d docDirectory nameOfPackage1 nameOfpackage2...

如果文件在默认包中，就应该运行：

javadoc -d docDirectory *.java

可以使用-link，用来为标准类添加超链接。例如：

javadoc -link http://docs.oracle.com/javase/8/docs/api *.java

那么，所有的标准类库类都会自动的链接到Oracle网站的文档。、
（这里参考了故克里的博文：Javadoc注释的生成规则）
——

参考文档

官方文档：http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html

本文作者： InjoyMario
本文链接： https://blog.csdn.net/InjoyMario/article/details/95043728
版权声明：本博客所有文章除特别声明外，均采用 ©BY-NC-SA 许可协议。转载请注明出处！

上穷青天揽星辰

关注

4
点赞
踩
14

收藏

觉得还不错? 一键收藏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录