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

àì夳堔傛蜴生んèń 2024-05-07 17:09 3阅读 0赞

![bf5c2d5d23f140edab17032162861db2.gif][]

> 🧑💻CSDN主页：[夏志121的主页][121]
> 
> 📋专栏地址：[Java基础+进阶+核心技术专栏][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 文件提供关于当前包的全局说明，
    可以简要描述该包中提供的类、函数和语言结构以及为何这些元素会彼此相关联。 */

[bf5c2d5d23f140edab17032162861db2.gif]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/07/9ae96d9afdd74c5aa72a4d165c238d8e.gif
[121]: https://blog.csdn.net/m0_61961937
[Java]: https://blog.csdn.net/m0_61961937/category_11368706.html?spm=1001.2014.3001.5482