《疯狂Java讲义(第3版)》.(李刚)——注释

我非常确定,作为开发人员我们都喜爱技术文档。我们喜欢阅读文档、写文档,更不用说维护文档了,我简直爱死它了!

《疯狂Java讲义(第3版)》.(李刚)——注释

1、注释的必要性:
1)自己或他人重构系统时方便理清楚这段代码的流程和思路。
2)增加自己代码的可读性。
3)当代码出现错误时注释代码可逐渐排查错误,缩小错误范围(我自己更喜欢debug)。
2、注释类型
1)单行注释。
在需要注释的前方加上双斜杠即可(//)

    public class LineComment
{
    //这是单行注释的范例
    public static void main(String args[])
    {
        //这只是一个单行注释的例子
        System.out.println("Single Line Comment");
    }
}

2)多行注释。
在需要注释的前方加上“/*”表示注释开始,结尾加上“*/”表示注释结束。
代码:

    public class MultiCommont
{
    /*
     *这是段注释的一个简单的例子
     *这里是函数入口main方法
     */
    public static void main(String args[])
    {
        System.out.println("Multi Lines Comments");
    }
}

3)文档注释。
文档注释是Java里面的一个比较厉害的功能,它可以用于注释类、属性、方法等说明,而且通过JDK工具javadoc直接生成相关文档,文档注释的基本格式为“/**...*/”,不仅仅如此,文档注释本身还存在语法
javadocTest:包括类、方法、成员变量的注释

package com.alex.demo01;

/**
 * Description
 * 

 * 
This is a demo of javadoc
 * 

 * 

 * 

 * @author Alex
 * @version 1.0
 */
public class JavaDocTest {
    /**
     * 简单测试成员变量
     */
    private String name;
    /**
     * 主方法,程序的入口
     * @param args
     */
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Test类:

package com.alex.demo01;

/**
 * Description
 * 

 * 
This is a demo of javadoc
 * 

 * 

 * 

 * @author Alex
 * @version 1.0
 */
public class Test {

    /**
     * 简单的成员变量
     */
    private int age;

    /**
     * Test的测试构造器
     */
    public Test(){

    }
}

javadoc 命令生产api文档:

javadoc -d *Test.java

参数详解:在windows命令行输入javaodc -help

图片 1

为了生产更详细的api文档,可以使用如下的javadoc标记:

图片 2

[1]文档和文档注释的格式化:
  生成的文档是HTML格式的,而这些HTML格式的标识符并不是javadoc加的,而是我们在写注释的时候写上去的。因此在格式化文档的时候需要适当地加入HTML标签,例如:

/**
 *This is first line.

 *This is second line.

 *This is third line.

 **/

  [2]文档注释的三部分:
  根据在文档中显示的效果,文档注释可以分为三个部分,这里举个例子:

/**
 *testDoc方法的简单描述
 *

testDoc方法的详细说明

*@param testInput String 打印输入的字符串 *@return 没有任何返回值 **/ public void testDoc(String testInput) { System.out.println(testInput); }

  简述:文档中,对于属性和方法都是现有一个列表,然后才在后面一个一个的详细说明,列表中属性名或者方法名后面那段说明都是简述。
  
  特殊说明:除开上边的两部分,最后一个部分就是特殊说明部分,特殊说明部分使用JavaDoc标记进行,这些都是JavaDoc工具能够解析的特殊标记,这一点下边章节将会讲到
  
  [3]使用javadoc标记:
  
  javadoc标记是java插入文档注释中的特殊标记,它们用于识别代码中的特殊引用。javadoc标记由“@”以及其后跟着的标记类型和专用注释引用组成。它的格式包含了三个部分:
  
  @、标记类型、专用注释引用

  有时候我们也可以直接理解为两个方面:@和标记类型、专用注释引用;Javadoc工具可以解析Java文档注释中嵌入的特殊标记,这些文档标记可以帮助自动从源代码生成完整的格式化API,标记用“@”符号开头,区分大小写,必须按照正确的大小写字母输入。标记必须从一行的开头开始,否则会被视为普通文本,而且按照规定应将相同名字的标记放一起,比如所有的@see标记应该放到一起,接下来看一看每一种标记的含义。
  
  @author(1.0):语法[@author name-text]
  
  当使用-author选项的时候,用指定的name-text在生成文档的时候添加“Author”项,文档注释可以包含多个@author标记,可以对每个@author指定一个或者多个名字。
  @deprecated(1.0):语法[@deprecated deprecated-text]
  添加注释,只是不应该再使用该API(尽管是可用的),Javadoc工具会将deprecated-text移动到描述前面,用斜体显示,并且在它前边添加粗体警告:“不鼓励使用”。deprecated-text的首句至少应该告诉用户什么时候开始不鼓励使用该API以及使用什么替代它。Javadoc仅将首句复制到概览部分和索引中,后面的语句还可解释为什么不鼓励使用,应该还包括一个指向替代API的{@link}标记【1.2版本用法】
对于Javadoc 1.2,使用{@link}标记,这将在需要的地方创建内嵌链接,如:

/**
 *@deprecated 在JDK X.X中,被{@link #methodName(paramList)}取代
 **/

【*:在上边的标记里面X.X指代JDK的版本,后边的链接链接的是方法的签名,methodName为方法名,paramList为参数列表】
对于Javadoc
1.1,标准格式是为每个@deprecated标记创建@see标记(它不可内嵌)
  

@exception(1.0):语法[@exception class-name description]
  @throws(1.2):语法[@throws class-name description]

  以上两个标记是同义词,用class-name和description文本给生成的文档添加“抛出”子标题,其中class-name是该方法可抛出的异常名。
  
  {@link}(1.2):语法[{@link name label}]
  
  出入指向指定name的内嵌链接,该标记中name和label的语法与@see标记完全相同,如下所述,但是产生的内嵌链接而不是在“参见”部分防止链接。该标记用花括号开始并用花括号结束,以使它区别于其他内嵌文本,如果需要在标签内使用“}”,直接使用HTML的实体表示法:
  

@param(1.0):语法[@param parameter-name description]

  
  给“参见”部分添加参数,描述可以继续到下一行进行操作,主要是提供了一些参数的格式以及描述
  

 @return(1.0):语法[@return description]

  用description本文添加“返回”部分,该文本应描述值的返回类型和容许范围
  
  @see(1.0):语法[@see reference]
  
  该标记是一个相对复杂的标记,添加“参见”标题,其中有指向reference的链接或者文本项,文档注释可包含任意数目的@see标记,它们都分组在相同的标题下,@see有三种格式:
@see “string” 注:该形式在JDK 1.2中没有用,它不打印引用文本
为string添加文本项,不产生链接,string是通过该URL不可用的书籍或者其他信息引用,Javadoc通过查找第一个字符为双引号(”)的情形来区分它前边的情况,比如:
@see “这是Java教材,主要是提供给初学者”
上边的注释将会生成:
参见:
  “这是Java教材,主要是提供给初学者”

@see Java某章节

添加URL#value定义的链接,其中URL#value是相对URL或者绝对URL,JavaDoc工具通过查找第一个字符小写符号(<)区分它与其他情况,比如:

@see 测试规范

上边的注释将会生成:
参见:
  测试规范
@see package.class#member label【比较常用的一种格式】
添加带可见文本label的链接,它指向Java语言中指定名字的文档。其中label是可选的,如果省略,则名字作为可见文本出现,而且嵌在HTML标记中,当想要缩写可见文本或不同于名字的可见文本的时候,可以使用label。 ——package.class#member是Java语言中的任何有效名字——包名、类名、接口名、构造函数名、方法名或域名——除了用hash字符(#)取代成员名前面的点之外,如果该名字位于带文档的类中,则Javadoc将自动创建到它的链接,要创建到外部的引用链接,可使用-link选项,使用另外两种@see形式中的任何一种引用不属于引用类的名字的文档。 ——label是可选文本,它是链接的可见标签,label可包含空白,如果省略label,则将显示package.class.member,并相对于当前类和包适当缩短 ——空格是package.class#member和label之间的分界符,括号内的空格不表示标签的开始,因此在方法各参数之间可使用空格 @see package.class#member的典型形式 引用当前类的成员

@see #field
@see #method(Type,Type,...)
@see #method(Type argname,Type argname,...)

引用当前包或导入包中的其他类

@see Class#field
@see Class#method(Type,Type,...)
@see Class#method(Type argname,Type argname,...)
@see Class

引用其他包(全限定)

@see package.Class#field
@see package.Class#method(Type,Type,...)
@see package.Class#method(Type argname,Type argname,...)
@see package.Class

@see package简单说明一下:
——第一套形式(没有类和包)将导致 Javadoc
仅搜索当前类层次。它将查找当前类或接口、其父类或超接口、或其包含类或接口的成员。它不会搜索当前包的其余部分或其他包(搜索步骤
4-5)。
——如果任何方法或构造函数输入为不带括号的名字,例如
getValue,且如果没有具有相同名字的域,则 Javadoc
将正确创建到它的链接,但是将显示警告信息,提示添加括号和参数。如果该方法被重载,则
Javadoc 将链接到它搜索到的第一个未指定方法。
——对于所有形式,内部类必须指定为 outer.inner,而不是简单的 inner。
——如上所述,hash 字符(#)而不是点(.)用于分隔类和成员。这使 Javadoc
可正确解析,因为点还用于分隔类、内部类、包和子包。当 hash
字符(#)是第一个字符时,它是绝对不可少的。但是,在其他情况下,Javadoc
通常不严格,并允许在不产生歧义时使用点号,但是它将显示警告。
  @see标记的搜索次序——JavaDoc将处理出现在源文件(.java)、包文件(package.html)或概述文件(overview.html)中的@see标记,在后两种文件中,必须完全限定使用@see提供的名字,在源文件中,可指定全限定或部分限定的名字,@see的搜索顺序为:
当前类或接口
任何包含类和接口,先搜索最近的
任何父类和超接口,先搜索最近的
当前包
任何导入包、类和接口,按导入语句的次序搜索
  @since(1.1):语法[@since since-text]
  用since-text指定的内容给生成文档添加“Since”标题,该文本没有特殊内部结构,该标记表示该改变或功能自since-text所指定的软件件版本后就存在了,例如:@since
JDK 1.4
  @serial(1.2):语法[@serial field-description]
  用于缺省的可序列化域的文档注释中,可选的field-description增强了文档注释对域的描述能力,该组合描述必须解释该域的意义并列出可接受值,如果有需要描述可以多行,应该对自Serializable类的最初版本之后添加的每个可序列化的域添加@since标记。
  @serialField(1.2):语法[@serialField field-name field-type
field-description]
  简历Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档,应该对每个ObjectStreamField使用一个@serialField标记
  @serialData(1.2):语法[@serialData data-description]
  data-description建立数据(尤其是writeObject方法所写入的可选数据和Externalizable.writeExternal方法写入的全部数据)序列和类型的文档,@serialData标记可用于writeObject、readObject、writeExternal和readExternal方法的文档注释中
  @version(1.0):语法[@version version-text]
  当使用-version选项时用version-text指定的内容给生成文档添加“版本”子标题,该文本没有特殊内部结构,文档注释最多只能包含一个@version标记。
  {@code}(1.5):语法[{@code text}]
  该标签等同于{@literal},里面可以直接过滤掉HTML的标签,可以不用<和>来显示(<和>),在这个代码块里面的text部分,可以直接书写代码,即使使用了Hello,在HTML里面也不会识别成为加粗的Hello,而还是原来的代码段Hello的格式输出
  {@docRoot}(1.3):语法[{@docRoot}]
  代表相对路径生成的文件的(目标)的根从任何产生的网页目录,当您要包括如版权页或公司徽标文件的时候它是有用的,你要引用所生成的网页,链接从每个页面底部的版权页面是常见的。(@docRoot将标记可用于在命令行,并在两个文档注释:这个标记是有效的,在所有文档注释:概述、包装类、接口、构造、方法和领域,包括任何标记文本的一部分(如@return
,@param和@deprecated的使用)。
  比如:

/** 
 * See the Copyright. 
 **/

  {@inheritDoc}(1.4):语法[{@inheritDoc}]
  继承(拷贝)文档从最近的“继承类或可执行的接口”到当前在这个标签的位置的文档注释内容,这使您可以编写更多与继承相关的一般性文档
  下边的情况比较适合:
在一个方法的主要描述块,在这种情况下,主要描述是整个继承树结构里面的类和接口的一个拷贝。
在文本参数返回的@return
@param和@throws等方法标记,在这种情况下,文本标记是整个层次结构里面标签的拷贝。
  {@linkplain}(1.4):语法[{@linkplain package.class#member
label}]
  和{@link}类似,除非链接的label是用普通文本的格式显示的,当文本是普通文本的时候该标签就能够起作用,例如:

Refer to {@linkplain add() the overridden method}

  这个会显示成:
Refer to the overridden method
  {@value}(1.4):语法[{@value package.class#field}]
  主要用来显示静态字段的值:

/**
 * The value of this constant is {@value}
 **/
public static final String SCRIPT_START = "script";

  [4]JavaDoc标记的举例:
  ——[$]一个使用JavaDoc标记的例子——

/**
 * @author Lang Yu
 * @version 1.2
 */
public class JavaDocBasic {
    /**
     * @see "Main Function JavaDoc"
     * @since JDK 1.4
     * @param args The params of console
     **/
    public static void main(String args[]){
        System.out.println("Hello World!");
    }
}

  例如有这样一小段代码,在我机器上我放在了D:Sourcework下,然后进入该目录下,使用下边的命令:

D:Sourcework>javadoc -d doc JavaDocBasic.java

  通过这样的命令使用,在执行该命令了过后电脑上有下边这样的输出,而且去目录下边可以看到一个doc文件夹,用浏览器打开里面的index.html就可以看到生成的文档的内容:
  

Loading source file JavaDocBasic.java...
Constructing Javadoc information...
Standard Doclet version 1.6.0_16
Building tree for all the packages and classes...
Generating docJavaDocBasic.html...
Generating docpackage-frame.html...
Generating docpackage-summary.html...
Generating docpackage-tree.html...
Generating docconstant-values.html...
Building index for all the packages and classes...
Generating docoverview-tree.html...
Generating docindex-all.html...
Generating docdeprecated-list.html...
Building index for all classes...
Generating docallclasses-frame.html...
Generating docallclasses-noframe.html...
Generating docindex.html...
Generating dochelp-doc.html...
Generating docstylesheet.css...

  ——[$]一个使用{@link}的例子——

/**
 * @author Lang Yu
 * @see java.lang.String
 */
public class JavaDocLink {
    private int a;
    private int b;
    /**
     * {@link #getAdd() getAdd()} Method
     * @return the result of (a + b)
     **/
    public int getAdd(){
        return a + b;
    }
}

 

1、注释的必要性:
1)自己或他人重构系统时方便理清楚这段代码的流程和思路。
2)增加自己代码…

Javadoc标记

介绍常用的javadoc,全部javadoc可以见官网的
javadoc。

我也知道,每次你创建一个类或者一个方法,你都会想到要为此写文档。我也很确定你很享受于写文档,就像你喜欢偶尔美味的汉堡一样。但是有时候,只是有时候,你会想要松懈一下,也许这次就跳过文档部分。不幸的是,这种行为会很快地失控。

@author

用于标记代码的作者,可以用a标签将个人博客或个人邮箱与自己的姓名绑定。
另外,在 JDK 代码中我们经常看到 @author
unascribed,意思是:“该代码第一原作者不是我,但我实在也不知道是谁,就记作无名氏吧”(这是多么严肃的一种版权意识啊)。

所以在这篇文章中,我想聊聊这个开发者的生活中关键但是通常被忽视并遗忘的部分。希望你会从此爱上文档,明白你的代码为什么能工作,能帮助你、你的团队和使用你的软件的数不尽的用户。

@value

可以用于生成被标记的常量字段的值。

为什么文档很重要

通常,开发者都不会忘记他们两个星期前写的代码。两个月以后甚至更长时间以后他们都会记得。即使我们保证我们从来不忘记我们写过的任何代码,写文档却有另一个理由并且更加重要。

{@inheritDoc}

继承父类的文档(包括@return @param
@throws),子类可以再加入自己的注释。其实在不写 {@inheritDoc}
的情况下也存在文档注释的继承。

在写代码前理清思路

我会举一个自己的例子:我有一个开发SlideshowFX里一个全新特性的想法,这时我就想直接开始写代码并实现它。但我知道我不是做这项工程的唯一一个有激情的开发者。所以我的典型行为是这样的:

1. 写出以下类主体
public class BurgersManager {
}
2. 思考:“那么,我应该在BurgersManager类中有些CRUD操作”
3. 写下:
public…
4. 思考:“我应该返回什么值?目前来说void就可以”
5. public void addBurger(Burger burger) {
// TODO implement that later
}
public …
6. 思考:“我应该返回被吃掉的汉堡的实例吗?还是void就可以?就像第4步那样。。。”
7. public void eat(Burger burger, boolean fast) {
// TODO …
8. 告诉自己:“糟糕,咖啡时间了,我的咖啡呢。。。”
9. 搜索,喝咖啡,和同事交谈
10. 然后告诉自己:“回去工作吧,我刚才在做什么来着?”

我知道,你在这个例子中看到了自己,对吧?在创造性工作刚开始的时候,我们的思路有些混乱,所以当你直接开始写代码,那么代码也会很混乱。在写代码之前就考虑文档能够帮你理清思路并清除列出你要用代码实现的事。所以第一步应该是写出以下代码:

/**
* 此类通过提供CRUD操作来管理汉堡
* 采用单件模式。可以使用{<a href='http://www.jobbole.com/members/57845349'>@link</a> #getInstance()}来获得这个管理器的实例。
* 之后可以用以下方法来调用CRUD操作:
*/

{<a href='http://www.jobbole.com/members/57845349'>@link</a> #addBurger(Burger)} 用来增加汉堡,并受管理于
* 单件实例 ;
* @作者 Thierry Wasylczenko
* @版本 0.1
* <a href='http://www.jobbole.com/members/chchxinxinjun'>@since</a> BurgerQueen 1.0
*/
public class BurgersManager {

}

这就是一个简短的例子,这个例子能够:

  • 强迫你思考你创建的类的目的是什么
  • 帮你确定你的需要
  • 即使是在你休息之后也能帮你想起来你在做什么
  • 帮助你预估还有什么是需要做的

{@link}、{@linkplain}

link 和 linkplain 的实参都是package.class#member
label
。唯一的不同就是因为字体不同,如果 label 是个纯文本,那就使用
linkplain 吧。

伙计,你是在团队中开发

你也许不是在单独工
作,你可能有尊敬的同事,你想和那些同事一起喝咖啡聊天。重点是,因为你喜欢他们,所以你想要帮助他们参与到你那令人兴奋的汉堡王的实现中去。为此,最好的做法就是确定他们在读你的代码时,有完美的文档参考。即使他们在你写代码之后的两个星期问你问题,你也能毫无犹豫地回答他们。

这就是另一个为什么文档很重要的理由:它能避免人们多次跑来问你你这复杂的算法是怎样运作的,或者为什么管理器中增加的汉堡没有同样被加到职工管理器的统计中去。在一个团队中,文档可以避免以下问题:

  • 在工作的时候被打断,之后难以返回继续工作;
  • 寻找可以回答问题的人,因为让其他成员知道了解自己是否能够回答问题;
  • 等待某个队员有时间回答他们的问题。
  • 所以写文档可以帮助团队提高生产力并专注于开发。

@since

根据官方文档解释,@since 表达的是被标记元素是哪个发布版本引入的。

让成功更进一步

这一点更加主观些。写Javadoc让我非常有成就感,因为当我再次使用我的API的时候,我写代码有文档参考,这帮我确保我没有忘记任何小细节。尽管我通常不会忘记,知道有文档在支撑我的记忆力也是件很棒的事。

看到IntelliJ
IDEA展示我的文档让我有“嘿,看,我就像是专业的,我做的东西太棒了,我甚至有文档噢”的感觉。在某些程度上的确是这样,不是吗?因为当你在使用一个
lib,其中的 log(String s, int i)
没有任何命名良好的参数描述,你一定像我一样在想“这个究竟是什么玩意儿?”。

不知道你怎样想的,我反正是觉得新的Javadoc设计特别赞。我认为让自己的文档整洁是非常棒的事。但是正如我说的,这只是我个人的感受。

@version

提到了 @since 就自然会联想到
@version,因为它们的实参都是版本相关的。@version
要表达的是被标记元素自己的版本(注意对比
@since),也就是说这个版本只要代码改过就应该发生变化,而 @since
是不会变的。

写Javadoc的小技巧

在Javadoc中你有一下很好的标签可以使用:

  • @author
  • @version
  • @param
  • @return
  • @exception/@throws
  • @see
  • @since
  • @serial/@serialField/@serialData
  • @deprecated

但是这篇文章的目的并不是详细解释所有标签,而是作为文档作者和开发人员,我想分享我在写我的Javadoc时使用的技巧。

@exception、@throws

它们完全是同义词,用于标记要抛出的异常。

使用@link和@linkplain来指向某些代码

在我的Javadoc中,如果有依赖关系或者对文档有用,我会提及其它类和方法。为了使方法和类的浏览更简便,你可以使用@link。它是这样工作的:

  • {@link BurgersManager} 指向一个类
  • {@link BurgersManager burgers manager} 指向带有标签的类
  • {@link #eat(Burger, boolean)} 指向此类中的某个方法
  • {@link #eat(Burger, boolean) eat} 指向此类中带有标签的某个方法
  • {@link BurgersManagers#eat(Burger, boolean)} 指向其他类中的某个方法
  • {@link BurgersManagers#eat(Burger, boolean) burgers manager eat}
    指向其他带有标签的类的某个方法

@link 和 @linkplain 的区别是后者不会生成等宽字体的代码。

@param @return @throws

标记参数,返回值,异常。

使用@code来表明代码段

通常你会在Javadoc中发现一段代码,用来说明怎样使用方法和类,或者提供其它例子。为了正确显示代码,并防止一些像这样的标记被打断,你可以使用@code。

{<a href='http://www.jobbole.com/members/java12'>@code</a> 
List&lt;Burger&gt; burgers = new ArrayList&lt;&gt;();
  for(int index = 0; index &lt; 10; index++) {
    burgers.add(new Burger(“Burger #” + index)); 
  }
}

@code会为你生成标记。

@deprecated

标记过时的方法或类。

使用@value来在文档中插入字段值

当你有一个常量,我可能想要它的值在文档中显示出来。有两个选择:

  • 自己插入这个值。但是如果这个值改变了,你必须更新你的文档,如果你绝对不会忘记这点,那你可以放心选择这个做法;
  • 使用@value来为你插入值,这样你就不用手动更新你的文档。

对我来说第二个选择是利用Javadoc工具的最佳方法,我会讨论这个方法。实际上,使用单一属性特别有用:

/**
* The default value for this field is {@value}.
* 这个域的默认值是{@value}.
*/
public static final String BURGER_SHOP_NAME = "Thierry's shop";

但你也可以指向其它常量,比如:

/**
* The default value for this field is {@value} when the value
* of {<a href='http://www.jobbole.com/members/57845349'>@link</a> #OWNER} is {@value #OWNER}.

* 这个域的默认值是{@value} 当
* {<a href='http://www.jobbole.com/members/57845349'>@link</a> #OWNER}的值为{@value #OWNER}.
*/
public static final String BURGER_SHOP_NAME = &quot;Thierry&#039;s shop&quot;;

/**
* The default owner of this awesome burger shop.

* 这家很棒的汉堡店的默认店主.
*/
public static final String OWNER = &quot; Thierry&quot;;

HTML标记

用@since来表明此特性的生效时间

通常,在你的代码中表明类或者方法何时开始生效非常有用。为此使用@since标签并在其后注明该特性执行的版本/年份:

/**
* This awesome class is for doing awesome things
* 这个棒呆了的类是用来做些棒呆了的事
* <a href='http://www.jobbole.com/members/chchxinxinjun'>@since</a> burger-core-0.1
* @version 0.2
*/
public class BurgersManager {

/**
* Allows to eat burgers
* 可以吃汉堡
* <a href='http://www.jobbole.com/members/chchxinxinjun'>@since</a> burger-core-0.2
*/
public void eat(Burger burger, boolean fast) {
// TODO
}
}

你可以看到,我把它用在了方法和类上,并且不止包含了版本号。事实上,现在我们的应用有很多不同的模块,这些模块可以有不同生命周期,即版本。说某个方法或者类从0.2版本开始生效并没有特别的意思。那么究竟是什么的0.2版本?这就是为什么我总是用一个相关的@since 来帮助我的同事第一眼就明白这些是什么时候开始生效的。

不止如此,这个标签的一个好处就是它可以帮你创建发布说明。等会儿,啥?不,并不是使用你最喜欢的IDE,比如IntelliJ
IDEA,然后查找包含“@since
burger-core-0.2″的文件。然后瞧,你可以找到自那个版本之后添加的所有方法和类。当然,这无法告诉你被更新的方法和类,而只会告诉你新添加的东西。但是你应该看到,这么简单的窍门多有用。

pre

可以使用<pre></pre>来显示代码原有的样子,比javadoc的{@code }块好用多了,后者根本不能保证换行、缩进等,适合用于文中嵌入的代码。

当然还有一些常见的如 <b></b><p></p><br><h#></h#>
可以用于美化格式,就不一一指出了,反正javadoc都是支持的嘛。

不要匿名,使用 @author

我非常讨厌的一件事:开发人员不承认自己的代码,并且不表明是他们为了一个糟糕的原因写了这糟糕的代码。如果你写了一段代码,要么承认它,要么去当经理。你可以用
@author
来表明你是这个类或者方法的作者。我认为把这标签既放在类上也放在方法上比较好,因为一个类的方法可能不是都是类的作者写的。

另一个好习惯就是,把一个方法或类的所有作者都加上。
试想一下,你和你的同事写了一个很棒的方法,而标签表明你是这个方法的唯一作者。有一天你去度假了,有人在读你的方法,但不是很明白并且想要一些细节。而是因为你被标为唯一的作者,他们不知道这个信息可以从和你一起写代码的同事那里很容易就获得。你知道我要说什么了,对吧?要记得给代码加@author来表
明作者。

其他

对非void方法要使用@return

我要说这一点对我来说非常有意义。有时候我看到类似以下例子中的代码就要跪了。

/** Get the address.
 * @return
 */
public String getAddress() { /* … */ }

为什么!?说真的,为什么你不填好@return?“因为只是一行而已,就是获得地址”。

不不不,请不要这样。如果你那样回答,是因为你的文档。怎么说呢,因为你的文档欠佳。是的,因为你可以很简单地写出一个更好的版本,而不是像以上你见到的糟糕的文档,
看:

/**
* Get the address of this burger shop. The address is of the following format:
* {<a href='http://www.jobbole.com/members/java12'>@code</a> address line 1
* address line 2
* zipcode city}
* @return the address of this burger shop or {<a href='http://www.jobbole.com/members/java12'>@code</a> null} if not filled.
*/

/**
*获取汉堡店的地址。地址格式:
* {<a href='http://www.jobbole.com/members/java12'>@code</a> 地址行1
* 地址行2
* 邮编 城市}
* @return 汉堡店的地址,如果没有填地址返回 {<a href='http://www.jobbole.com/members/java12'>@code</a> null}.
*/

好太多了,对吧?这样你的文档就有用了。我一直试着寻找给代码写文档的合适方法,因为有时候读者只读
@return 的内容,有时候也会读 @return
上面的内容,你添加一些说明就可以简单地避免疑惑。

写中文注释的建议

  • 使用中文的句号作为文档注释的结尾。
  • 在中文中的英文和数字符号前后加入空格。

用@param说明参数的含义

有什么比看到方法使用一个像 i
这样的意义不明的参数而不加任何文档更加沮丧呢?有时候你可以通过方法的名字来猜到这个参数的目的,可是有时候就不行。所以在你的文档里,你应该使用@param来表明这个参数的含义,并说明可能的有效值。在我们的例子中,i可以是日志的级别:INFO,
DEBUG或者TRACE。这个标签另一个很有用的例子就是当这个值对应的是一个索引。有些情况下索引从0开始,有些情况下从1开始。@param就是用来描述这一区别的标签。

包注释

推荐使用 package-info.java 的方式,因为这样可以使用注解

生成文档

在代码中有文档是非常好的,但是现在你必须生成文档。所以你可以使用JDK提供的Java文档工具来生成它。

通过执行类似这样的命令:

javadoc {packages|source-files} [options]

你可以指定想要生成文档的包名或文件名,多个名字用空格分隔。

以下简要描述了一些jJavadoc工具能够接受的选项:

  • -author: 在生成的文档中生成@author用
  • -d: 要在当前目录之外生成文档的目录
  • -nodeprecated: 不为被标为@deprecated的代码生成文档
  • -protected: 包含protected和public类和类成员
  • -private: 包含private类和类成员
  • -public: 只包含public类和类成员

像IDE之类的工具也可以生成你的文档,但是如果它很好地格式化并且可以提供预览。

一些像Maven和Gradle这样的依赖管理工具也带有生成文档的阶段或任务。这很棒,因为你的文档可以一直紧随代码的发布来生成,这样它就一直是最新的。

RESTful风格注解

如果需要为RESTful风格的接口书写文档的话,推荐使用apiDoc的规范,也可以生成html文档,着实好用,强力推荐👍

总结

文档对于你的整个团队非常重要。它能帮你理清你在写什么代码,更重要的是,你为什么这样实现它。

希望这篇文章能让你想要写出更好的文档。如果是这样的话请告诉我你是否写了文档,你是怎样写的。

我的推特@twasyl,或者在下面留言都可以!

参考文章

  • 细节见真功之
    Javadoc
  • javadoc – The Java API Documentation
    Generator
You can leave a response, or trackback from your own site.

Leave a Reply

网站地图xml地图