Java编程规范-注释

た 入场券 2023-10-08 12:55 122阅读 0赞

注释

加上注释，格式尽量和规范保持一致
Java 程序有两类注释： 实现注释 (implementation comments) 和 文档注释 (document comments) 。

实现注释 是使用 /* … */ 和 // 界定的注释，用于注释代码或者注释特殊的实现。

文档注释 也称为 javadoc ，是 Java 所特有的，由 /** … */ 界定，可以通过 javadoc 工具转换成 HTML 文件，主要是描述代码段的说明，以编程手册的形式呈献给其他开发人员。

通常注释应该是给代码一个总的描述 ， 或者提供从代码本身 不太容易看出的附加性信息 。注释的内容应只与读代码和理解代码有关。例如，关于相应的包 (package) 是如何构建，以及存放在什么目录中，不应该包括在注释中，对代码中 不太明显的设计意图进行说明 是应该的，但也应该 避免 对一些明显的信息进行 重复说明 ，尽量 避免 那些随着代码的维护 会过时的注释 。

注释的基本要求

方法及参数尽量加上注释，注释率不强制要求30%
1、适当注释 主要流程步骤 、 设计思路 和 关键细节 等，以辅助阅读和加深理解；
2、对 非 显而易见 的设计增加足够的注释，但要尽量 避免 注释信息和代码 过多的重复 ；
3、源程序的注释率 ( 注释行数占总行数的百分比 ) 应该在 30% 以上，不要求每个文件都达到这个要求，这个要求以模块为单位进行度量；
4、短注释可以跟在代码行的后面，但必须离代码够近。如果多个短注释出现在同一类型的代码后面，他们应该尽可能保持一种风格；
5、长注释应该加在其所描述的代码段之前，和前面的代码用空行分开，和所描述的代码段保持相同的缩进；
6、 注释要和代码保持一致，修改代码要同时修改相应的注释， 无用的注释要及时删除 ；
7、对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时必须加以注释，说明其物理含义，变量、常量的注释应该在其上方相邻位置或右方；
8、不要在一行代码内部插入注释；
9、禁止使用注释方式保留废弃的代码，废弃的代码必须删除 ；
10、所有的枚举类型字段必须要有注释，说明每个数据项的用途；

文件头注释

不强制要求按照此规范处理
文件头注释位于文件最前端， package 语句之前，两者之间用空行隔开。
文件头注释采用 实现注释 格式，内容包括：公司版权声明、产品名称、模块名、文件创建时间、文件修订记录等。
示例：

  1. /* 
  2. * ------------------------------------------------------------------ 
  3. * Copyright © 2015 DtDream Scien ce and Technology Co.,Ltd. All rights reserved. 
  4. * ------------------------------------------------------------------ 
  5. *       Product: net 
  6. *   Module Name: GateWay 
  7. *  Date Created: 2015-02-09 
  8. *   Description: 
  9. * ------------------------------------------------------------------ 
  10. * Modification History 
  11. * DATE            Name           Description 
  12. * ------------------------------------------------------------------ 
  13. * 2015-02-09      秦始皇 01234 
  14. * ------------------------------------------------------------------ 
  15. */

类和接口的注释

要求注释，但不强制要求完全按照此规范处理
类和接口注释使用 javadoc 风格， 置于 class 或者 interface 关键字所在行之前。
注释包括功能描述、作者、版本时间等内容。
@author作者
@since表示从哪个版本开始就有这个类或者接口
@see引用
@deprecated表示不建议使用该类或者接口
示例：

  1. package com.dtdream.demo; 
  3. import java.util.HashMap; 
  4. import java.util.Map; 
  6. /** 
  7. * Description ... 
  8. * @author 秦始皇 01234 
  9. * @since 1.0 
  10. */ 
  11. public class DemoTest { 
  12.     ... 
  13. }

类方法的注释

要求注释，但不强制要求完全按照此规范处理。方法参数要仔细说明
类方法的注释使用 javadoc 风格， 置于 方法声明或定义之前。
注释内容：列出方法的一句话功能描述、作者、输入参数、输出参数、返回值、异常等。
@author作者
@param参数
@return返回值
@throws非运行时异常
@exception运行时异常
@since表示从哪个版本开始就有这个类或者接口
@deprecated表示不建议使用该类或者接口
示例：
【正确用法】

  1. /** 
  2. * De s cription ... 
  3. * @author 秦始皇 01234 
  4. * @param long usrIndex 用户索引 
  5.   * @return UsrInfo 用户信息对象 
  6.   * @since 1.2 此方法添加于 1.2 版本 
  7.   */ 
  8. public UsrInfo getUser(long usrIndex) { 
  9.     ... 
  10. }

类属性的注释

不强制要求按照此规范处理，但是必要的说明是需要的，格式尽量按照规范处理，
实体类用swagger模式也可
类属性的注释使用 javadoc 风格，放在属性 定义之前。
示例：
【格式 1 ： 需要多行描述时采用格式 1 】

  1. /** 
  2. * 属性描述 
  3.   * 属性描述 
  4.   */ 
  5. private String usrName;

【格式 2 ： 单行描述采用格式 2 】

  1. /** 属性描述 */ 
  2. private String usrAddr;

方法内部代码块注释

方法里必要的注释还是需要的，格式尽量按照规范处理
方法内部的注释使用 实现注释 。

1、实现注释与其注释的代码在同一缩进级别或者位于代码行尾部；

示例：
【 错误用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  2.     UsrInfo usrInfo = getUsrInfo(usrName); 
  4. /* 注释 */ 
  5.     doSomething(); 
  7. /* 重设用户年龄 */ 
  8.      usrInfo.usrAge = usrAge; 
  10. /* 将用户置为在线状态 */ 
  11.      usrInfo.isOnLine = true; 
  13. /* 清零用户离线时间 */ 
  14.     usrInfo.offLineTime = 0; 
  15. }

【正确用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  2.     UsrInfo usrInfo = getUsrInfo(usrName); 
  4.     /* 注释 */ 
  5.     doSomething(); 
  7.     usrInfo.usrAge = usrAge;     /* 重设用户年龄 */ 
  8.     usrInfo.isOnLine = true;     /* 将用户置为在线状态 */ 
  9.     usrInfo.offLineTime = 0;     /* 清零用户离线时间 */ 
  10. }
2、注释不要封闭在由星号或者其他字符绘制的框架内；

示例：
【 错误用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  2.    /******************* 
  3.     *      注释         * 
  4.     *******************/ 
  5.     doSomething(); 
  6. }

【正确用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  2.     /* 注释 */ 
  3.     doSomething(); 
  4. }
3、注释应与其描述的代码相近，对代码的注释应放在其上方，并与其上面的代码用空行隔开；

示例：
【错误用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  2.     /* 注释 1 */ 
  3.     doSomething1(); 
  4.     /* 注释 2 */ 
  5.     doSomething2(); 
  6. }

【正确用法】

  1. private void setUsrInfo(String usrName, int usrAge) { 
  3.     /* 注释 1 */ 
  4.     doSomething1(); 
  6.     /* 注释 2 */ 
  7.     doSomething2(); 
  8. }

发表评论

表情：
评论列表 （有 0 条评论，122人围观）

还没有评论，来说两句吧...

相关阅读

    相关 java代码注释规范

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期

    灰太狼灰太狼/ 0 赞/ 407 阅读