Java编程规范-注释
注释
加上注释，格式尽量和规范保持一致 Java 程序有两类注释： 实现注释 (implementation comments) 和 文档注释 (document comments) 。
实现注释 是使用 /* … */ 和 // 界定的注释，用于注释代码或者注释特殊的实现。
文档注释 也称为 javadoc ，是 Java 所特有的，由 /** … */ 界定，可以通过 javadoc 工具转换成 HTML 文件，主要是描述代码段的说明，以编程手册的形式呈献给其他开发人员。
通常注释应该是给代码一个总的描述 ， 或者提供从代码本身 不太容易看出的附加性信息 。注释的内容应只与读代码和理解代码有关。例如，关于相应的包 (package) 是如何构建，以及存放在什么目录中，不应该包括在注释中，对代码中 不太明显的设计意图进行说明 是应该的，但也应该 避免 对一些明显的信息进行 重复说明 ，尽量 避免 那些随着代码的维护 会过时的注释 。
注释的基本要求
方法及参数尽量加上注释，注释率不强制要求30% 1、适当注释 主要流程步骤 、 设计思路 和 关键细节 等，以辅助阅读和加深理解； 2、对 非 显而易见 的设计增加足够的注释，但要尽量 避免 注释信息和代码 过多的重复 ； 3、源程序的注释率 ( 注释行数占总行数的百分比 ) 应该在 30% 以上，不要求每个文件都达到这个要求，这个要求以模块为单位进行度量； 4、短注释可以跟在代码行的后面，但必须离代码够近。如果多个短注释出现在同一类型的代码后面，他们应该尽可能保持一种风格； 5、长注释应该加在其所描述的代码段之前，和前面的代码用空行分开，和所描述的代码段保持相同的缩进； 6、 注释要和代码保持一致，修改代码要同时修改相应的注释， 无用的注释要及时删除 ； 7、对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时必须加以注释，说明其物理含义，变量、常量的注释应该在其上方相邻位置或右方； 8、不要在一行代码内部插入注释； 9、禁止使用注释方式保留废弃的代码，废弃的代码必须删除 ； 10、所有的枚举类型字段必须要有注释，说明每个数据项的用途；
文件头注释
不强制要求按照此规范处理 文件头注释位于文件最前端， package 语句之前，两者之间用空行隔开。 文件头注释采用 实现注释 格式，内容包括：公司版权声明、产品名称、模块名、文件创建时间、文件修订记录等。 示例：
/*
* ------------------------------------------------------------------
* Copyright © 2015 DtDream Scien ce and Technology Co.,Ltd. All rights reserved.
* ------------------------------------------------------------------
* Product: net
* Module Name: GateWay
* Date Created: 2015-02-09
* Description:
* ------------------------------------------------------------------
* Modification History
* DATE Name Description
* ------------------------------------------------------------------
* 2015-02-09 秦始皇 01234
* ------------------------------------------------------------------
*/ 类和接口的注释
要求注释，但不强制要求完全按照此规范处理 类和接口注释使用 javadoc 风格， 置于 class 或者 interface 关键字所在行之前。 注释包括功能描述、作者、版本时间等内容。 @author作者 @since表示从哪个版本开始就有这个类或者接口 @see引用 @deprecated表示不建议使用该类或者接口 示例：
package com.dtdream.demo;
import java.util.HashMap;
import java.util.Map;
/**
* Description ...
* @author 秦始皇 01234
* @since 1.0
*/
public class DemoTest {
...
} 类方法的注释
要求注释，但不强制要求完全按照此规范处理。方法参数要仔细说明 类方法的注释使用 javadoc 风格， 置于 方法声明或定义之前。 注释内容：列出方法的一句话功能描述、作者、输入参数、输出参数、返回值、异常等。 @author作者 @param参数 @return返回值 @throws非运行时异常 @exception运行时异常 @since表示从哪个版本开始就有这个类或者接口 @deprecated表示不建议使用该类或者接口 示例： 【正确用法】
/**
* De s cription ...
* @author 秦始皇 01234
* @param long usrIndex 用户索引
* @return UsrInfo 用户信息对象
* @since 1.2 此方法添加于 1.2 版本
*/
public UsrInfo getUser(long usrIndex) {
...
} 类属性的注释
不强制要求按照此规范处理，但是必要的说明是需要的，格式尽量按照规范处理， 实体类用swagger模式也可 类属性的注释使用 javadoc 风格，放在属性 定义之前。 示例： 【格式 1 ： 需要多行描述时采用格式 1 】
/**
* 属性描述
* 属性描述
*/
private String usrName; 【格式 2 ： 单行描述采用格式 2 】
/** 属性描述 */
private String usrAddr; 方法内部代码块注释
方法里必要的注释还是需要的，格式尽量按照规范处理 方法内部的注释使用 实现注释 。
1、实现注释与其注释的代码在同一缩进级别或者位于代码行尾部；
示例： 【 错误用法】
private void setUsrInfo(String usrName, int usrAge) {
UsrInfo usrInfo = getUsrInfo(usrName);
/* 注释 */
doSomething();
/* 重设用户年龄 */
usrInfo.usrAge = usrAge;
/* 将用户置为在线状态 */
usrInfo.isOnLine = true;
/* 清零用户离线时间 */
usrInfo.offLineTime = 0;
} 【正确用法】
private void setUsrInfo(String usrName, int usrAge) {
UsrInfo usrInfo = getUsrInfo(usrName);
/* 注释 */
doSomething();
usrInfo.usrAge = usrAge; /* 重设用户年龄 */
usrInfo.isOnLine = true; /* 将用户置为在线状态 */
usrInfo.offLineTime = 0; /* 清零用户离线时间 */
} 2、注释不要封闭在由星号或者其他字符绘制的框架内；
示例： 【 错误用法】
private void setUsrInfo(String usrName, int usrAge) {
/*******************
* 注释 *
*******************/
doSomething();
} 【正确用法】
private void setUsrInfo(String usrName, int usrAge) {
/* 注释 */
doSomething();
} 3、注释应与其描述的代码相近，对代码的注释应放在其上方，并与其上面的代码用空行隔开；
示例： 【错误用法】
private void setUsrInfo(String usrName, int usrAge) {
/* 注释 1 */
doSomething1();
/* 注释 2 */
doSomething2();
} 【正确用法】
private void setUsrInfo(String usrName, int usrAge) {
/* 注释 1 */
doSomething1();
/* 注释 2 */
doSomething2();
} 腾讯云开发者
