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

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

你也许不是在单独工作，你可能有尊敬的同事，你想要帮助他们参与到项目中去。为此，最好的做法就是确定他们在读你的代码时，有完美的文档参考。即使他们在你写代码之后的两个星期问你问题，你也能毫无犹豫地回答他们。

这就是另一个为什么文档很重要的理由：它能避免人们多次跑来问你你这复杂的算法是怎样运作的。所以写文档可以帮助团队提高生产力并专注于开发。

使用@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 的区别是后者不会生成等宽字体的代码。

使用@code来表明代码段

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

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

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

自己插入这个值。但是如果这个值改变了，你必须更新你的文档，如果你绝对不会忘记这点，那你可以放心选择这个做法；

使用@value来为你插入值，这样你就不用手动更新你的文档。

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

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

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

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

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

不要匿名，使用 @author

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

对非void方法要使用@return

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

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

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

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

用@param说明参数的含义

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

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

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

javadoc {packages|source-files} [options]

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

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

-author: 在生成的文档中生成@author用

-d: 要在当前目录之外生成文档的目录

-nodeprecated: 不为被标为@deprecated的代码生成文档

-protected: 包含protected和public类和类成员

-private: 包含private类和类成员

-public: 只包含public类和类成员

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

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

总结

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