Java中注释的使用是有原则的

Java提供了3种类型的注释

例如:


  1. // this is a single-line comment x = 1; // a single-line comment after code 

多行注释(C风格)

Java同样提供跨越多行的注释类型。这种类型的注释以紧跟着一个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。这种类型注释的开始和结束分界符可以在同一行里也可以在不同的行上。例如:


  1. /* This is a c-style comment */ /* This is also a c-style comment, spanning multiple lines */ 

注意:C风格的注释不可以嵌套使用。比如下面的用法:


  1. /* A comment looks like /* This is a comment */ blah blah blah */ 

上面的用法会造成语法错误,因为Java编译器只把第一个 */ 当做注释来处理。(编译器认为注释在第一个“*/”就结束了)。

你可以在多行注释里嵌入单行注释:


  1. /* This is a single-line comment: // a single-line comment */ 

以及在单行注释里使用多行注释:


  1. // /* this is // a multi-line // comment */ 

文档注释

文档注释是一种与多行注释很类似的特殊注释,它可以用来为你的源代码产生外部文档。这种注释以紧跟着两个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。例如:


  1. /** This is a documentation comment */ /** This is also a documentation comment */ 

这里有一些关于文档注释的重要事情要注意

javadoc文档生成器会把文档注释里的所有文本都添加到一个HTML段落里。这意味着,在文档注释里的任意文本都会被格式化为一个段落;空格和换行符会被忽略。如果你想要特殊的格式,你必须要在文档注释里使用HTML标签。

如果文档注释以超过两个的星号开始,那么javadoc就认为这些星号是用来在源码里创建一个“框”框住注释的,并忽略多余的星号。例如:

该注释仅保留“This is the start of a method”文本。

javadoc会忽略文档注释里处于行首的星号。例如:

该注释仅保留“This is a doc comment on multiple lines that I want to stand out in source code, looking “neat””文本。

常见的用法如下:

该用法是为了突出注释。要注意的是,这属于文档注释(即使这不是你所想的那样),并会在产生的文档里出现注释的内容。

什么时候使用文档注释

你(至少)应该在任意的公有类、接口、方法和源码里的类或实例变量前面使用文档注释。这样可以让javadoc针对代码产生简单的文档,它列出了公共实体

和每个实体的简要说明。你同样可以在非公共方法前面使用文档注释,不过需要使用一个javadoc选项来它们产生文档。相比于公有实体,在非公有实体上使
用文档注释显得没那么重要(它的接口不会暴露出来……)。但如果你要注释代码,你同样可以使用文档注释。

什么时候使用单行注释

任意时候都可以!

关于注释,我有一个简单的建议,在你想写常规注释(不是用来描述类、接口、方法或者变量的文档注释)的时候可以使用单行注释。

为什么?因为你可以轻易地使用多行注释去“注释掉”你的代码段(“注释掉代码”意味着把一段代码的词法状态变为一段注释,让编译器忽略这段代码)。举个例子:


  1. x = 1; /* set x to 1 */ y = 2; /* set y to 2 */ f(x, y); /* call f with x and y */ 

要把上面三行代码注释掉,你可能需要在每一行的前面使用单行注释:


  1. // x = 1; /* set x to 1 */ // y = 2; /* set y to 2 */ // f(x, y); /* call f with x and y */ 

或者在还没有加注释的地方加上多行注释:


  1. /* x = 1; */ /* set x to 1 */ /* y = 2; */ /* set y to 2 */ /* f(x, y);*/ /* call f with x and y */ 

或者分解或删除已存在的注释的“结束注释”分解符:


  1. /* x = 1; /* set x to 1 * / y = 2; /* set y to 2 * / f(x, y); /* call f with x and y * / */ 

这些用法都糟糕透了。如果原始代码使用下面的注释,那么事情就好办多了:


  1. x = 1; // set x to 1 y = 2; // set y to 2 f(x, y); // call f with x and y 

如此一来,只需使用多行注释把代码围起来你就可以轻松把它注释掉:


  1. /* x = 1; // set x to 1 y = 2; // set y to 2 f(x, y); // call f with x and y */ 

在你需要使用注释的时候尽量使用单行注释。

什么时候使用多行注释

阅读了上面的内容后,这个问题变得很明显了。只使用多行注释来注释代码段,不要用以其他目的。

来源:51CTO

时间: 2024-10-01 23:54:38

Java中注释的使用是有原则的的相关文章

我的Android进阶之旅------>对Java中注释/**@hide*/的初步认识

        今天写一个调节系统背光亮度的时候,参考了Android中的Setting源码,在源码中有这么一段代码: private static final int MAXIMUM_BACKLIGHT = android.os.PowerManager.BRIGHTNESS_ON;         然后我模仿它的代码,来进行编写我的应用,但是当我copy这段代码后报错      报错内容如下: BRIGHTNESS_ON cannot be resolved or is not a fiel

Java正则表达式(三)、代码量统计工具(统计java源文件中注释、代码、空白行数量)

       比如想统计一个Java程序员一天写代码的工作量(如:有效代码多少行.空行多少.注释多少行等),这个小工具也许能做为一个参考的依据.     思路:因为每个java源文件的内容基本包括java语句.空白行.注释三部份组成(不包括注解),所以要统计某个文件这三部份的内容各占多少时,只需写三个匹配这几部份内容的正则表达式即可.然后通过IO流读取文件中的每一行,并根据正则匹配的结果,累加每部份匹配的数量即可.     注释行:单行注释(//).多行注释.文档注释.正则:((//)|(/\\

如何使用JS的正则表达式检查 java中的文档注释? (用于代码高亮)

问题描述 例如:在java 中可以这样写文档注释/***这个是注释**/我想实现的效果是/***这个是注释**/现在我想用JS 的正则表达式 匹配他我写了如下的代码但是就是不起作用,只能匹配 /** 其他剩下的都不能匹配.MultiLineCComments : new RegExp('/\*[\s\S]*?\*/', 'gm'),希望哪为朋友帮帮忙,帮我修改一下这个正则表达式,使其能够正常工作.谢谢!问题补充:其实我这段代码是MultiLineCComments : new RegExp('/

全面解析Java中的注解与注释_java

注解一.什么是 Annotation? (注解 or 注释)Annotation, 准确的翻译应该是 -- 注解. 和注释的作用完全不一样. Annotation 是JDK5.0及以后版本引入的一个特性. 与类.接口.枚举是在同一个层次,可以成为java 的一个类型. 语法是以@ 开头 简单来说, 注释是程序员对源代码的类,方法,属性等做的一些记忆或提示性描述(比如这个方法是做什么用的),是给人来看的. 注解则是Java 编译器可以理解的部分,是给编译器看的. 举个简单的例子来看一下注解的使用和

Java 批量删除html中注释内容的方法_java

其实删除html文本中的注释有很多方法,这里就自己随便写了一个处理方法,权当笔记,有需要的同学可以参考. html文本的注释有几个特点: 1. 成对出现,有开始就一定有结束. 2. 注释标签没有嵌套,注释开始标签(以下称为 <!--)下一个一定是其对应的结束标签(以下称为 -->). 3. 一行中可能有多个注释标签对儿. 4. 注释也可以换行. 大致有以下几种情况: 复制代码 代码如下: <html>  <!--This is a head-->  <head&g

Java中的类反射机制

一.反射的概念 :反射的概念是由Smith在1982年首次提出的,主要是指程序可以访问.检测和修改它本身状态或行为的一种能力.这一概念的提出很快引发了计算机科学领域关于应用反射性的研究.它首先被程序语言的设计领域所采用,并在Lisp和面向对象方面取得了成绩.其中LEAD/LEAD++ .OpenC++ .MetaXa和OpenJava等就是基于反射机制的语言.最近,反射机制也被应用到了视窗系统.操作系统和文件系统中. 反射本身并不是一个新概念,它可能会使我们联想到光学中的反射概念,尽管计算机科学

jAVA 中的定时器

 在 Java 应用程序中定时执行任务 Java 中Timer 类的简洁用法 所有类型的 Java 应用程序一般都需要计划重复执行的任务.企业应用程序需要计划每日的日志或者晚间批处理过程.一个 J2SE或者 J2ME 日历应用程序需要根据用户的约定计划闹铃时间.不过,标准的调度类 Timer 和 TimerTask 没有足够的灵活性,无法支持通常需要的计划任务类型.在本文中,Java 开发人员 Tom White 向您展示了如何构建一个简单通用的计划框架,以用于执行任意复杂的计划任务. 我将把

关于Java中停止线程执行的方法总结

Java中停止线程执行的方法 一.暂停或停止线程的理论 在Java编程中,要暂停或停止当前正在运行的线程,有几种方法.对于把线程转入睡眠Sleep状态,使用Thread.sleep()是最正确的方式.或许有人会问,为什么不使用等待wait()或通知notify()?要知道,使用等待或通知都不是很好的方式.线程可以使用等待wait()实现被阻塞,这属于条件等待的方式,当条件满足后,又会从阻塞转为等待状态.尽管可以在等待wait()条件那里放一个超时设置,但等待wait()的设计目的不是这样的,等待

java中关于dismiss方法的使用

问题描述 java中关于dismiss方法的使用 myDialog.dismiss( )比如这条语句中是关闭一个对话框的意思吗dismiss还有哪些方面的应用 解决方案 看下这个函数的源码上面的注释信息,jdk源码上的英文注释就是很好的参考文档的. 解决方案二: 这和java语言没有关系,这只是dialog对象定义的方法罢了.你也可以写一个类,定义一个叫dismiss的方法. 在英文字面看来,dismiss就是消失的意思. 解决方案三: java中waitnotifynotifyAll的使用方法