注释规范

Java中的注释一般分为三种：文档注释、单行注释和多行注释。具体如下：

文档注释

/**
 * Class that exposes the Spring Boot version. Fetches the
 * {@link Name#IMPLEMENTATION_VERSION Implementation-Version} manifest attribute from the
 * jar file via {@link Package#getImplementationVersion()}, falling back to locating the
 * jar file that contains this class and reading the {@code Implementation-Version}
 * attribute from its manifest.
 * <p>
 * This class might not be able to determine the Spring Boot version in all environments.
 * Consider using a reflection-based check instead: For example, checking for the presence
 * of a specific Spring Boot method that you intend to call.
 *
 * @author Drummond Dawson
 * @author Hendrig Sellik
 * @author Andy Wilkinson
 * @since 1.3.0
 */

java

文档注释一般用于类注释、方法注释、字段注释。

单行注释

private ConfigurableEnvironment prepareEnvironment(SpringApplicationRunListeners listeners,
        DefaultBootstrapContext bootstrapContext, ApplicationArguments applicationArguments) {
    // Create and configure the environment
    ConfigurableEnvironment environment = getOrCreateEnvironment();
    configureEnvironment(environment, applicationArguments.getSourceArgs());
    ConfigurationPropertySources.attach(environment);
    listeners.environmentPrepared(bootstrapContext, environment);
    DefaultPropertiesPropertySource.moveToEnd(environment);
    Assert.state(!environment.containsProperty("spring.main.environment-prefix"),
            "Environment prefix cannot be set via properties.");
    bindToSpringApplication(environment);
    if (!this.isCustomEnvironment) {
        environment = convertEnvironment(environment);
    }
    ConfigurationPropertySources.attach(environment);
    return environment;
}

java

单行注释一般用于方法内。对部分复杂逻辑进行说明。

多行注释

/*
 * Copyright 2012-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

java

类中各种注释的位置

/*
 * 这是文件注释，使用多行注释，一般用于说明源文件的版权信息
 */
package org.depsea.example;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

/**
 * 这里是类注释，使用文档注释
 */
public class CommentExample {
    
    /**
     * 字段注释，使用文档注释
     */
    private LocalDateTime dateTime;
    
    /**
     * 这里是方法注释，使用文档注释
     */
    public void setDateTime(LocalDateTime dateTime) {
        this.dateTime = dateTime;
    }
    
    /**
     * 这里是方法注释，使用文档注释
     */
    public String getDateTimeStr() {
        // 方法内的注释，使用单行注释
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
        return formatter.format(this.dateTime);
    }
}

java

Copyright

固定如下：

/**
 * Copyright (c) 2021-${YEAR} DEPSEA.ORG Inc. All Right Reserved.
 */

javascript

可以在IDEA中的 Settings -> Editor -> Copyright 中设置项目的Copyright。

类注释

/**
 * TODO
 *
 * @author ${USER}
 * @since 1.0.0 [${DATE} ${TIME}]
 */

java

需要在IDEA的 Help -> Edit Custom VM Options... 中添加

-Duser.name=<your name>

如

-Duser.name=Zhang San

${USER} 变量会读取环境变量中设置的 user.name，如果没有设置，则会读取Windows的计算机名。

TODO 需要替换为类说明注释。如类的功能从类名上已经可以明确知道，允许省略（但不推荐）类说明注释。

方法注释

/**
 * Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}.
 * <p>If this method returns {@code true}, it means {@link #convert(Object, Class)} is capable
 * of converting an instance of {@code sourceType} to {@code targetType}.
 * <p>Special note on collections, arrays, and maps types:
 * For conversion between collection, array, and map types, this method will return {@code true}
 * even though a convert invocation may still generate a {@link ConversionException} if the
 * underlying elements are not convertible. Callers are expected to handle this exceptional case
 * when working with collections and maps.
 *
 * @param sourceType the source type to convert from (may be {@code null} if source is {@code null})
 * @param targetType the target type to convert to (required)
 * @return {@code true} if a conversion can be performed, {@code false} if not
 * @throws IllegalArgumentException if {@code targetType} is {@code null}
 */
boolean canConvert(@Nullable Class<?> sourceType, Class<?> targetType);

java

方法注释一般输入 /** 回车后，IDEA会自动带出。

方法注释包括以下几个部分

• 方法功能说明
• 参数说明
• 返回值说明
• 异常说明

原则上所有方法都必须加注释，注释中应明确说明方法的作用。

字段注释

/**
 * 应答数据
 */
private T data;

java

字段注释应使用文档注释，不允许使用单行或多行注释。更不允许直接在字段后面添加注释。

方法内部注释

如果方法内部逻辑比较复杂，应使用单行注释在代码中加以说明。增加程序的可读性。

Java中常用的文档注解说明

文档注解	使用位置	说明
@author	类注释	类的创建人或修改人，一般如果修改了某个类，应当将自己添加到类的作者列表中。
@since	类注释、方法注释	表示这个类或者方法从哪个版本开始创建的。
@version	类注释	用于指定类的版本信息。不常用，一般只用 @since。
@see	类注释、方法注释、字段注释	用于创建超链接到其他类、方法、字段或包的文档。
@param	方法注释	用于描述方法参数的含义和用途。
@return	方法注释	用于描述方法的返回值的含义和用途。
@throws	方法注释	用于描述方法可能抛出的异常情况。
@exception	方法注释	用于描述方法可能抛出的异常情况。与 @throws 类似，但是一般使用 @throws。
@deprecated	类注释、方法注释、字段注释	说明类、方法、字段已过时，并需要说明应使用哪个类或方法替代。

在 Java8 中新加了3个注解，分别是 @apiNote、@implSpec、@implNote，详细信息可以参考 Javadoc conventions in the presence of default methods，这3个注解虽然在文档注释中可以使用，单并没有在正式的Javadoc文档中记录。

文档注解	使用位置	说明
@apiNote	类注释	这个注解通常用于标记一个方法或类的公共API，并提供有关如何使用API的额外信息。
@implSpec	类注释、方法注释	这个注解通常用于标记一个方法的规范说明，提供有关方法如何实现的详细信息。它通常用于接口和抽象类中定义的方法（默认方法）。
@implNote	类注释	这个注解通常用于提供方法实现的额外说明，特别是在@implSpec中提到的子类可以选择覆盖方法时。

注意

这些自定义注解可以帮助开发者更清晰地记录代码的设计和实现细节，以便其他开发者能够更容易地理解和使用你的代码。注意，这些注解不是Java标准库的一部分。

有关注释规范的更详细的信息可以参考官方的Javadoc规范文档：Documentation Comment Specification for the Standard Doclet (JDK 17)

禁止

不允许使用不支持的文档注解，如 @date、@description、@createBy 等。无需在类注释中添加修改说明。

下面的图片中是所有可以使用的文档注解，以及他们可以出现的位置。凡是下面表格中没有的，应当一律禁止使用（@apiNote、@implSpec、@implNote除外）。

image-20230919150252403

其他说明

• 多个作者应使用多个 @author 注解，不允许在一个 @author 中添加多个姓名。