在Java中正确使用注释
Java提供了3种类型的注释:
单行注释(C++风格)
在Java中最简单的注释是单行注释。它以两个正斜杠开始并到行尾结束。例如:
// this is a single-line commentx = 1; // a single-line comment after code
多行注释(C风格)
Java同样提供跨越多行的注释类型。这种类型的注释以紧跟着一个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。这种类型注释的开始和结束分界符可以在同一行里也可以在不同的行上。例如:
/* This is a c-style comment *//* This is also ac-style comment, spanningmultiple lines */
注意:C风格的注释不可以嵌套使用。比如下面的用法:
/* A comment looks like/* This is a comment */blah blah blah*/
上面的用法会造成语法错误,因为Java编译器只把第一个 */ 当做注释来处理。(编译器认为注释在第一个“*/”就结束了)。
你可以在多行注释里嵌入单行注释:
/* This is a single-line comment:// a single-line comment*/
以及在单行注释里使用多行注释:
// /* this is// a multi-line// comment */
文档注释
文档注释是一种与多行注释很类似的特殊注释,它可以用来为你的源代码产生外部文档。这种注释以紧跟着两个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。例如:
/** This is a documentation comment *//** This is also adocumentation comment */
这里有一些关于文档注释的重要事情要注意:
- javadoc文档生成器会把文档注释里的所有文本都添加到一个HTML段落里。这意味着,在文档注释里的任意文本都会被格式化为一个段落;空格和换行符会被忽略。如果你想要特殊的格式,你必须要在文档注释里使用HTML标签。
- 如果文档注释以超过两个的星号开始,那么javadoc就认为这些星号是用来在源码里创建一个“框”框住注释的,并忽略多余的星号。例如:
/**********************************This is the start of a method**********************************/
该注释仅保留“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"***************************************/
该注释仅保留“This is a doc comment on multiple lines that I want to stand out in source code, looking “neat””文本。
- 常见的用法如下:
/******************************************...******************************************/
该用法是为了突出注释。要注意的是,这属于文档注释(即使这不是你所想的那样),并会在产生的文档里出现注释的内容。
什么时候使用文档注释
你(至少)应该在任意的公有类、接口、方法和源码里的类或实例变量前面使用文档注释。这样可以让javadoc针对代码产生简单的文档,它列出了公 共实体 和每个实体的简要说明。你同样可以在非公共方法前面使用文档注释,不过需要使用一个javadoc选项来它们产生文档。相比于公有实体,在非公有实体上使 用文档注释显得没那么重要(它的接口不会暴露出来……)。但如果你要注释代码,你同样可以使用文档注释。
什么时候使用单行注释
任意时候都可以!
关于注释,我有一个简单的建议,在你想写常规注释(不是用来描述类、接口、方法或者变量的文档注释)的时候可以使用单行注释。
为什么?因为你可以轻易地使用多行注释去“注释掉”你的代码段(“注释掉代码”意味着把一段代码的词法状态变为一段注释,让编译器忽略这段代码)。举个例子:
x = 1; /* set x to 1 */y = 2; /* set y to 2 */f(x, y); /* call f with x and y */
要把上面三行代码注释掉,你可能需要在每一行的前面使用单行注释:
// x = 1; /* set x to 1 */// y = 2; /* set y to 2 */// f(x, y); /* call f with x and y */
或者在还没有加注释的地方加上多行注释:
/* x = 1; */ /* set x to 1 *//* y = 2; */ /* set y to 2 *//* f(x, y);*/ /* call f with x and y */
或者分解或删除已存在的注释的“结束注释”分解符:
/*x = 1; /* set x to 1 * /y = 2; /* set y to 2 * /f(x, y); /* call f with x and y * /*/
这些用法都糟糕透了。如果原始代码使用下面的注释,那么事情就好办多了:
x = 1; // set x to 1y = 2; // set y to 2f(x, y); // call f with x and y
如此一来,只需使用多行注释把代码围起来你就可以轻松把它注释掉:
/*x = 1; // set x to 1y = 2; // set y to 2f(x, y); // call f with x and y*/
在你需要使用注释的时候尽量使用单行注释,不要写无用的注释。
你也可以看看之前发布的9个最有趣的代码注释,尽管它是搞笑的。
什么时候使用多行注释
阅读了上面的内容后,这个问题变得很明显了。只使用多行注释来注释代码段,不要用以其他目的。
转载于:https://www.cnblogs.com/mlj007/p/4329650.html
在Java中正确使用注释相关推荐
- java 中覆 写tostring_如何在Java中正确覆盖toString()?
如何在Java中正确覆盖toString()? 听起来有点愚蠢,但我需要帮助我的toString()方法,这是非常irking. 我尝试在网上查找,因为toString是搞砸了,"没有找到K ...
- 如何在 Java 中正确使用 wait, notify 和 notifyAll – 以生产者消费者模型为例
欢迎支持笔者新作:<深入理解Kafka:核心设计与实践原理>和<RabbitMQ实战指南>,同时欢迎关注笔者的微信公众号:朱小厮的博客. wait, notify 和 noti ...
- java中注解和注释的说明
1,什么是注解 注解(Annotation)是一种元数据形式.属于java中的一中数据类型.是书写于java代码中的,但是书写的位置被固定在类.方法.变量.参数的前面.不会改变程序的操 ...
- 如何在 Java 中正确使用 wait, notify 和 notifyAll?
简介 wait,notify,notifyAll,都是属于object对象提供的方法,但在实际工作中怎么使用这几个方法,确是很多程序员清楚,不够明白,在群里问,有人说,哪个线程想wait,就用 ...
- Java中注解(非注释^_^) --转载
本文将向你介绍J2SE5.0中的新特性之一:注解.本文将从什么是注解:J2SE5.0中预定义的注解:如何自定义注解:如何对注解进行注解以及如何在程序中读取注解5个方面进行讨论. 一.什么是注解 说起注 ...
- 用java编写战舰 游戏吗_如何在Java中正确建模战舰游戏
我正在尝试为我的小组在大学里做的"游戏"项目创建战舰游戏.我之前从未真正使用过GUI,几乎所有输出都在Eclipse控制台中. 首先,我创建了一个GUI类,它实际上是我的" ...
- 如何在Java中正确使用Apache Commons数学库中的ZipfDistribution?
java apache-commons-math zipf 温馨提示:将鼠标放在语句上可以显示对应的英文. 或者 切换至中英文显示 我想基于遵循Zipf分布的单词(来自字典)创建数据源 ...
- java中有哪几种注释方式_在 Java 中, 有多种注释方法,其中 __________ 适用于单行注释。...
对划线句子理解正确的一项是( ). 下列对于事件一产生的原因,不正确的是( ). 现行标准<建设工程监理规范>(GB/T50319-2013)是______. 简述长善救失的教学原则. 化 ...
- java将数字替换为空_将数字替换为java中正确位置的单词
实际上我正试图用用户给出的句子中的数字替换为单词.本案例日期格式;例如:我的生日是在16/6/2000,我是 java的新手 – >成为->我的生日是七月十六日,我是java的新手 这是代 ...
最新文章
- Java性能优化最易操作的10大技巧!
- 这是马?小鹏发布可骑乘「智能马」,四不像长相太奇葩!
- Lidar-RCNN:基于稀疏点云的3D目标检测网络(CVPR2021)
- #error “OpenCV 4.x+ requires enabled C++11 support“解决方法
- JAVA入门级教学之(方法递归)
- (软件工程复习核心重点)第一章软件工程概论-第二节:软件工程
- 51Nod 1009 数字1的数量 数位dp
- Leetcode-1154 Ordinal Number Of Date(一年中的第几天)
- 无法获取计算机名,Spring Cloud常见问题之:无法注册主机名
- 数据链路层之以太网协议和网络层IP协议
- Axure教程-新手入门基础(小白强烈推荐!!!)
- 算法竞赛入门经典(第二版) —— 第一章 程序设计入门
- Dwz 国产框架 JUI 分页组件下拉菜单bug解决方案
- 魔兽世界经典游戏ID搞笑篇 魔兽世界搞笑ID
- (4) epics 中新建一个ioc的整体过程
- vmware设置虚拟机静态ip
- oracle rac节点重启,oracle RAC一个节点频繁重启解决
- Python之Flask框架(一)
- 手机APP测试都要注意哪些问题?
- 树莓派安装Google拼音输入法
热门文章
- 在Mono 2.8上部署ASP.NET MVC 2
- C++11多线程----线程管理
- 区块链BAAS平台:公共或私人区块链编程以用于各种用途
- 本地浏览器缓存sessionStorage(临时存储) localStorage(长期存储)的使用
- c#多线程操作界面控件的简单实现
- 触摸屏Sensor叠构实例学习记录(一)
- WinForm部署问题
- 《MySQL排错指南》——1.9 许可问题
- discuz x2.5插件开发傻瓜图文教程,用demo说话
- c# 扩展方法奇思妙用高级篇五:ToString(string format) 扩展