提高代码质量的秘诀：类、方法、字段和包注释

最新推荐文章于 2024-04-30 10:42:39 发布

夏志121

最新推荐文章于 2024-04-30 10:42:39 发布

阅读量1.2k

点赞数 5

CC 4.0 BY-SA版权

分类专栏： Java基础+进阶+核心技术文章标签： java java-ee 开发语言后端注释

本文链接：https://blog.youkuaiyun.com/m0_61961937/article/details/131032213

Java基础+进阶+核心技术专栏收录该内容

128 篇文章

订阅专栏

本文介绍了Java中的不同类型的注释，包括单行、多行、类注释、方法注释、字段注释和包注释，强调了javadoc工具在生成专业文档中的作用。类和方法注释通常包含参数、返回值和异常信息，而通用注释如@since、@author和@version提供了版本和作者信息。包注释可以通过package-info.java或package.html文件来创建。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

🧑‍💻优快云主页：夏志121的主页

📋专栏地址：Java基础+进阶+核心技术专栏

JDK提供了一个很有用的工具，叫做javadoc，它可以由源文件生成一个HTML文档。如果在源代码中添加以特殊定界符/**开始的注释，那么你就可生成一个看上去具有专业水准的文档。Java文档注册可以提高代码的可读性和维护性。其中的关键是使用合适的注释，Java的注释有许多种类：

🍢 一、注释的插入

在Java中添加注释非常简单。只需要在代码前面加上两个斜线“//”，就可以在该行之后添加单行注释：

// 这是单行注释

你还可以将任何文本放在一个多行注释块内：

/*

● 多行注释。

●  在块注释中，可以分解成多段注释。 */

🍣 二、类注释

/**

● 这是类的说明 */

其中，星号(*)后的内容是用于为Java文档工具生成类库文档所需的标记。它包含了类的一般描述和一些相关信息。这样的类注释使得您的代码复用更加容易。

🍤 三、方法注释

/**

这是方法的说明
@param p1 参数说明
@param p2 参数说明
@return 返回值说明
@exception 异常说明 */

这种注释中带有参数说明、返回值说明和异常说明，旨在帮助开发人员理解当前方法的目的和如何使用它。

🍥 四、字段注释

字段注释应在字段的定义之前进行，在格式上与变量声明类似：

/**

对于该字段的描述 */ 
private String fieldName;

这样可以对自身或者其他开发人员解释一个字段存在的意义，非常有利于代码理解和后期维护。

🥮 五、通用注释

标记 @since text 会建立一个 “since”(始于)条目。text（文本）可以是对引入这个特性的版本的描述。例如：@since 1.7.1。

@author name

这个标记将建立一个“author”(作者)条目，可以由多个@author标记，每个@author标记对应一个作者。并不是非得使用这个标记，你的版本控制系统能够更好地跟踪作者。

@version text

这个标记将建立一个“version”(版本)条目。这里的text可以是对当前版本的任何描述。

通过@see和@link标记，可以使用超链接，链接到javadoc文档的相关部分或外部文档。

🍡 六、包注释

要想产生包注释，就需要在每个包目录中添加一个单独的文件。可以由如下两个选择：

1、提供一个名为package-info.java的Java文件。这个文件必须包含一个初始的Javadoc注释，以/**和*/界定，后面是一个package语句。它不能包含更多的代码或注释。

2、提供一个名为package.html的HTML文件，抽取标记<body>...<body>之间的所有文本

/**

package-info 文件提供关于当前包的全局说明，
可以简要描述该包中提供的类、函数和语言结构以及为何这些元素会彼此相关联。 */