Th技术开发白皮书

注释规范

2021/7/16 javadoc

# javadoc规范

# 前言

很多开发人员对Javadoc都不重视，认识不到Javadoc的作用，很多人都是这样认为的：“我只要写好功能就够了，写Javadoc太浪费时间，也没啥作用，还不如用写Javadoc的时间再多些个功能呢！”，我们知道注释是为了解释代码的作用的，是为了将来给自己或者别人快速了解代码的，在方法内一般用行注释//的比较多，是针对一小块代码做出解释的，而Javadoc的作用是针对整个方法或者整个类做一个简要的概述的，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了Javadoc的在别人使用到类时，将鼠标悬停到类上或者方法上，javadoc会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用

# 注释语法

​ 在开始的 /** 之后，第一行或几行是关于类、变量和方法的主要描述

之后，你可以包含一个或多个各种各样的 @ 标签。每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*).多个相同类型的标签应该放成一组。如下常见得方法注释：

 /**
   * xxx
   * @param xxx
   * @return xxx
   * @author xxxx
   * @last update date: xxx
   */

具体语法如下：

@author 标识一个类的作者 @author description
@deprecated 指名一个过期的类或成员 @deprecated description
{@docRoot} 指明当前文档根目录的路径 Directory Path
@exception 标志一个类抛出的异常 @exception exception-name explanation
{@inheritDoc} 从直接父类继承的注释 Inherits a comment from the immediate surperclass
{@link} 插入一个到另一个主题的链接 {@link name text}
{@linkplain} 插入一个到另一个主题的链接，但是该链接显示纯文本字体 Inserts an in-line link to another topic.
@param 说明一个方法的参数 @param parameter-name explanation
@return 说明返回值类型 @return explanation
@see 指定一个到另一个主题的链接 @see anchor
@serial 说明一个序列化属性 @serial description
@serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData description
@serialField 说明一个ObjectStreamField组件 @serialField name type description
@since 标记当引入一个特定的变化时 @since release
@throws 和 @exception标签一样. The @throws tag has the same meaning as the @exception tag
{@value} 显示常量的值，该常量必须是static属性 Displays the value of a constant, which must be a static field.
@version 指定类的版本 @version info

# 约束条件

  • 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，统 一规范注释（见模版）。

  • 【强制】所有的抽象方法（包括接口中的方法） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能

    说明： 对子类的实现要求，或者调用注意事项，请一并说明。

  • 【强制】所有的类都必须添加创建者信息

  • 【强制】方法内部单行注释，在被注释语句上方另起一行，使用// 注释。方法内部多行注释使用/* */注释，注意与代码对齐。

  • 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清 楚。专有名词与关键字保持英文原文即可

  • 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改

    说明： 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去 了导航的意义

  • 【参考】注释掉的代码尽量要配合说明，而不是简单的注释掉

    说明： 代码被注释掉有两种可能性： 1） 后续会恢复此段代码逻辑。 2） 永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码） 。

  • 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻 辑； 第二、能够描述业务含义，使别的程序员能够迅速了解到代码 背后的信息。完全没注释的大段代码对于阅读者形同天书，注释是 给自己看的，即使隔很长时间，也能清晰理解当时的思路； 注释也是给继任者看的，使其能够快速接替自己的工作

  • 【参考】好的命名、代码结构是自解释的，注释力求精简准确表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑 一旦修改，修改注释是相当大的负担

  • 【强制】特殊注释标记，请注明标记人与标记时间。注意及时处 理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就 是来源于这些标记处的代码

    1) 待办事宜（TODO） :     （ 标记人，标记时间， [预计处理时间] ）表示需要实现，但目前还未实现的功 

能。这实际上是一个 Javadoc 的标签，目前的 Javadoc还没有实现，但已经被广泛使用。只能应用于 

类，接口和方法（因为它是一个 Javadoc 标签） 。 

2) 错误，不能工作（FIXME） :      （标记人，标记时间， [预计处理时间] ） 在注释中用 FIXME 标记某代 

码是错误的，而且不能工作，需要及时纠正的情况。 

3) 需要改进的功能(XXX) ：该标识，说明标识处代码虽然实现了功能，但是实现的方法有待商榷，希望 

将来能改进，要改进的地方会在说明中简略说明。

# 举例

# web层

  • 正例

    整个类得描述，方法描述（作者，时间，描述，版本，参数，返回参数

image-20210716113840044

  • 反例

1生成注释没有描述

2入参名称替换之后，没有同步修改@param后得入参名称

3方法名或者类名上方根本没有注释

image-20210716113927799

# service层

  • 正例

    清晰看出整个接口是做是什么，每个方法做什么 需要什么参数

    image-20210716114057585

  • 反例

像这种不写注释得，谁能看出来方法是干啥得，这种就需要花时间去看逻辑

image-20210716114128946

# domain层

  • 正例

    domain中model,dto相应得类注释与字段注释是必要得

    image-20210716114146606

    image-20210716114208516

  • 反例

1啥注释没有，使用改dto中字段就需要看表。有些表中没有得字段。怎么使用？？？

2枚举类如果不加文本注释如下：那你开发是不是得疯狂切换数据库和idea

在一开始就注释好，方便

image-20210716114241703

image-20210716114246428

# dao层

Mapper接口最需要注释，因为如果sql比较复杂，比较长条件比较多其他开发人，使用改模块sql时，需要花费大量时间去匹配符合得方法

  • 正例

    尤其是根据 条件查询，除非是表中多条件支持得，一般可以注明根据哪些条件查

    image-20210716114428716

  • 反例

    没加文本注释得，需要检查xml中每个sql是干啥得比较耗时，还不好定位问题

    image-20210716114447865

  • common

  • 正例

    此处为国际化，常量类层国际配置必须加文本注释，同一模块返回状态码很多，不加注释很容是使用错误，不能准确返回状态值

    image-20210716114530040

  • 反例

    别说别人使用，自己写多了是不是也冒星星

    image-20210716114543228

# doc模版

  • files
/**
 * @Title:${project_name}
 * @Package:${package_name}
 * @Description:
 * @Author:chenyer@itonghui.org
 * @Date:${date}
 * version: v1.0
 */
  • types
/** 
 * @Copyright (c) by anhui tonghui information technology Co., Ltd.
 * @All right reserved.
 * @Create Date: ${date}${time}
 * @Create Author: chenye@itonghui.org
 * @File Name: ${file_name}
 * @Last version: 1.0
 * @Function:
 * @Last Update Date:
 * @Change Log:
 */
  • fields
/**
 * @Fields:${field}
 */
  • methods
/**
 * 方法描述
 *
 * @Author:chenye@itonghui.org
 * @date: ${date} ${time} 
 * ${tags}
 */
  • overriding methods
/**
 * 方法描述
 *
 * author: chenye@itonghui.org
 * @date: ${date} ${time}
 * ${tags} 
 * ${see_to_overridden} 
 */

下载地址->： IDEA注释模板配置

性能优化