Java 注释

Java 注释

单行注释：// 注释内容

多行注释：/* … 注释内容….*/

文本注释：/* * .. 注释内容…. */

---

文本注释：/* * .. 注释内容…. */

文本注释能够自动地生成文档。在JDK中有个javadoc的工具 （ 用法: javadoc [options] [packagenames] [sourcefiles] [@files] ），可以由源文件生成一个HTML文档。使用这种方式注释源文件的内容：专业，快速、有效、便于修改并且能够源文件的保存而保存起来。当修改源文件时，也可能对这个源代码的需求等一些注释性的文字进行修改，那么，这时候可以将源代码和文档一同保存，而不用再另外创建一个文档。

文档注释位置

（1）类注释。类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。
这个规则也适用于接口（interface）注释。
（2）方法注释。方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。
（3）属性注释。默认情况下，javadoc只对公有（public）属性和受保护属性（protected）产生文档——通常是静态常量。
（4）包注释。类、方法、属性的注释都直接放到Java的源文件中，而对于包的注释，无法放到Java文件中去，只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时，package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释，后面还会有更进一步的解释。
（5）概要注释。除了包注释外，还有一种类型的文档无法从Java源文件中提取，就是对所有类文件提供概要说明的文件。同样的，也可以为这类注释单独新建一个HTML文件，这个文件的名字为“overview.html”，它的和标记之间的内容都会被提取。

javadoc 标签

标签	描述	示例
@author	标识一个类的作者	@author description
@deprecated	指名一个过期的类或成员	@deprecated description
{@docRoot}	指明当前文档根目录的路径	Directory Path
@exception	标志一个类抛出的异常	@exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释	Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接	{@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	Inserts an in-line link / to another topic.
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@see	指定一个到另一个主题的链接	@see anchor
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。	Displays the value of a constant, which must be a static field.
@version	指定类的版本	@version info

代码中特殊注释——TODO、FIXME、XXX、HACK

TODO：英语翻译为待办事项，备忘录。如果代码中有该标识，说明在标识处有功能代码待编写，待实现的功能在说明中会简略说明。

FIXME：可以拆成短语，fix me ，意为修理我。如果代码中有该标识，说明标识处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明。

XXX：如果代码中有该标识，说明标识处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明。

HACK：英语翻译为砍。如果代码中有该标识，说明标识处代码我们需要根据自己的需求去调整程序代码。

Eclipse中特殊的注释：
在Eclipse中，TODO、FIXME和XXX都会被Eclipse的task视图所收集。
在开发过程中在合适的位置添加合适的注释是非常有必要的，我们可以在任务完成前检查这些标记。
Window—>Show View—>Tasks