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

评价:
0
(0用户)

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

 

本文出自:https://blog.csdn.net/m0_61961937/article/details/131032213

注册并通过认证的用户才可以进行评价!

admin:系统自动奖励,+10,  

发表评论