首页

【Java语言编码规范】实现注释和文档注释

标签:注释     发布时间:2023-01-10   

阅读《Java语言编码规范》第5节 注释(Comments) - 实现注释(implementation comments)和文档注释(document comments)

Java 程序有两类注释:实现注释(implementation comments)和文档注释(document @b@comments)。实现注释是那些在 C++中见过的,使用/*...*/和//界定的注释。文档注释(被称@b@为"doc comments")是 Java 独有的,并由/**...*/界定。文档注释可以通过 javadoc 工具转@b@换成 HTML 文件。

5.1 实现注释的格式(Implementation Comment Formats) - 块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。

5.1.1 块注释(Block Comments) @b@块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以@b@及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的块注释应该@b@和它们所描述的代码具有一样的缩进格式。@b@块注释之首应该有一个空行,用于把块注释和代码分割开来,比如:@b@ /* @b@ * Here is a block comment. @b@ */ @b@ @b@块注释可以以/*-开头,这样 indent(1)就可以将之识别为一个代码块的开始,而不会重排它。@b@ /*- @b@ * Here is a block comment with some very special @b@ * formatting that I want indent(1) to ignore. @b@ * @b@ * one @b@ * two @b@ * three @b@ */ @b@ @b@注意:如果你不使用 indent(1),就不必在代码中使用/*-,或为他人可能对你的代码运行@b@indent(1)作让步。
5.1.2 单行注释(Single-Line Comments) @b@短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写@b@完,就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中@b@单行注释的例子:@b@ if (condition) { @b@ /* Handle the condition. */ @b@ ... @b@ }
5.1.3 尾端注释(Trailing Comments) @b@极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。@b@若有多个短注释出现于大段代码中,它们应该具有相同的缩进。@b@以下是一个 Java 代码中尾端注释的例子:@b@ if (a == 2) { @b@ return TRUE; /* special case */ @b@ } else { @b@ return isPrime(a); /* works only for odd a */ @b@ }
5.1.4 行末注释(End-Of-Line Comments) @b@注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然@b@而,它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子:@b@ if (foo > 1) { @b@ // Do a double-flip. @b@ ... @b@ } @b@ else { @b@ return false; // Explain why here. @b@ } @b@ //if (bar > 1) { @b@ // @b@ // // Do a triple-flip. @b@ // ... @b@ //} @b@ //else { @b@ // return false; @b@ //}

5.2 文档注释(Documentation Comments)

文档注释描述 Java 的类、接口、构造器,方法,以及字段(field)。每个文档注释都会被置于注@b@释定界符/**...*/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前:@b@ /** @b@ * The Example class provides ... @b@ */ @b@ public class Example { ... @b@ @b@注意顶层(top-level)的类和接口是不缩进的,而其成员是缩进的。描述类和接口的文档注释的@b@第一行(/**)不需缩进;随后的文档注释每行都缩进 1 格(使星号纵向对齐)。成员,包括构造函@b@数在内,其文档注释的第一行缩进 4 格,随后每行都缩进 5 格。@b@若你想给出有关类、接口、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现@b@块注释(见 5.1.1)或紧跟在声明后面的单行注释(见 5.1.2)。例如,有关一个类实现的细节,应@b@放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。@b@文档注释不能放在一个方法或构造器的定义块中,因为 Java 会将位于文档注释之后的第一个声@b@明与其相关联。
<<推荐下载>>
  • (1) 阿里巴巴Java开发手册8种不同版本
  • (2) Web前端开发视频教程
  • (3) 30+明星讲师PPT课件分享一线大厂架构实战经验
  • (4) java开发_架构篇_视频资源分享_v2208
  • (5) java开发_高级篇_视频资源分享_v2208
  • (6) java开发_进阶篇(中级)_视频资源分享_v2208
  • (7) java开发_入门篇_视频资源分享_v2208
  • (8) 微信小程序开发视频1+167源码+实战demo等下载
  • (9) easy-shopping电子商务java源码(附脚本和安装文档说明)下载
  • (10) java常用的72份知名实用的电子书下载
  • (11) java开发性能优化资料整理大全(8份电子文档+3份实战优化)下载
  • (12) 9个常用的算法设计资料和100以上视频课件内容下载
  • (13) vue开发必备常用手册16件下载
  • (14) 21种不同技术集群方案(es、flink、redis、nginx、zk、lvs、kafka、mysql、k8s等)参考资料下载
  • (15) 20种技术代码规范(js/java/dba/阿里/华为/oracle/mysql等)参考资料下载
  • (16) 微服务五套资料(0-1,架构设计,springcloud,nacos等)下载
  • (17) 架构师(28知识图谱+3套简历模板+6套架构实战文档等)完整资料整理下载
  • (18) 大数据18套实战基础知识+8套简历模板下载
  • (19) 并发编程全套(7套+阿里巴巴+亿级实战等)实战资料下载
  • (20) Kafka九套学习整理知识点全套(面试+笔记+代码api+命令+容备等)资料下载
  • (21) java全套9个不同方向类型的面试题(基础+核心+大厂+架构师+近万套题库等)下载
  • (22) JAVA开发常用API帮助文档大全(超52种以上技术资料,高手必备)下载
  • (23) springcloud超详细139件全套学习实战资料( 视频课件+源码demo+文档资料等)下载
  • 更多推荐>>
  • <<热门文章>>