注释---知识点总结
2018-06-18 03:00:41来源：未知 阅读 ()
1. 注释分类
Java语言的注释一共有单重类型：
l 单行注释
l 多行注释
l 文档注释
1.1. 单行注释和多行注释
单行注释就是在程序中注释一行代码；多行注释是指一次性地将程序中多行代码注释掉。
格式：
l 单行注释：//注释内容
l 多行注释：/*
注释内容
*/
Java中，/* */注释不能嵌套使用。
添加注释也是调试程序的一个重要方法。如果觉得某段代码可能有问题，可以先把这段代码注释掉起来，让编译器忽略这段代码，再次编译、运行，如果程序可以正常执行，则可以说明错误就是由这段代码引起的，这样就缩小了错误所在的范围，有利于排错；如果依然出现相同的错误，则可以说明错误不是这段代码引起的，同样也缩小了错误所在的范围。
1.2. 文档注释
如果编写Java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API（应用程序接口）文档。
格式：/**
文档注释内容
*/
注释的插入
Javadoc实用程序从下面几个特性中抽取信息：
l 包
l 公有类与接口
l 公有的和受保护的构造器及方法
l 公有的和受保护的域
应该为上面几部分编写注释。注释应该放置在所描述特性的前面。
类注释
类注释必须放在import语句之后，类定义之前。
方法注释
每一个方法注释必须放在所描述的方法之前。常用标记：
l @param
这个标记将对当前方法的“param”（参数）部分添加一个条目。
l @return
这个标记将对当前方法添加“return”（返回）部分。
l @throws
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。
域注释
只需要对公有域（通常指的是静态常量）建立文档。
通用注释
l @author
这个标记将产生一个“author”（作者）条目。
l @version
这个标记将产生一个“version”（版本）条目。
l @since
这个标记将产生一个“since”（始于）条目。
l @deprecated
这个标记将对类、方法或变量添加一个不再使用的注释。
l @see
这个标记将在“see also”部分增加一个超级链接。
包与概述注释
想要产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两种选择：
1） 提供一个以package.html命名的HTML文件。在标记<body>…</body>之间的所有文本都会被抽取出来。
2） 提供一个以package-info.java命名的Java文件。这个文件必须包含一个初始的以 /** 和 */ 界定的javadoc注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。
2. 注释规约
摘取自《阿里巴巴Java开发手册》。
1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用 /** 内容 */ 格式，不得使用 // xxx 方式。
说明： 在 IDE 编辑窗口中， Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释； 在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
2. 【强制】所有的抽象方法（包括接口中的方法） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
说明： 对子类的实现要求，或者调用注意事项，请一并说明。
3. 【强制】所有的类都必须添加创建者和创建日期。
4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
6. 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
反例： “TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
7. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
说明： 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
8. 【参考】 谨慎注释掉代码。 在上方详细说明，而不是简单地注释掉。 如果无用，则删除。
说明： 代码被注释掉有两种可能性： 1） 后续会恢复此段代码逻辑。 2） 永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码） 。
9. 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑； 第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路； 注释也是给继任者看的，使其能够快速接替自己的工作。
10. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
反例：
// put elephant into fridge put(elephant, fridge);
方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。
11. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1） 待办事宜（TODO） :（标记人，标记时间， [预计处理时间]）
表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签） 。
2） 错误，不能工作（FIXME） :（标记人，标记时间， [预计处理时间]）
在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。
标签：
版权申明：本站文章部分自网络，如有侵权，请联系：west999com@outlook.com
特别注意：本站所有转载文章言论不代表本站观点，本站所提供的摄影照片，插画，设计作品，如需使用，请与原作者联系，版权归原作者所有
- 设计模式---类之间的关系知多少 2020-06-07
- java方法句柄-----1.方法句柄类型、调用 2020-05-28
- Java--Java的设计模式----单例模式 2020-05-26
- 【JavaSE】泛型知识点（总结） 2020-05-25
- SpringBoot+Mybatis---这一篇就够了！ 2020-05-18
IDC资讯： 主机资讯 注册资讯 托管资讯 vps资讯 网站建设
网站运营： 建站经验 策划盈利 搜索优化 网站推广 免费资源
网络编程： Asp.Net编程 Asp编程 Php编程 Xml编程 Access Mssql Mysql 其它
服务器技术： Web服务器 Ftp服务器 Mail服务器 Dns服务器 安全防护
软件技巧： 其它软件 Word Excel Powerpoint Ghost Vista QQ空间 QQ FlashGet 迅雷
网页制作： FrontPages Dreamweaver Javascript css photoshop fireworks Flash
