改善Java文档的理由、建议和技巧【转】

in 旧文字 with 0 comment

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

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

为什么文档很重要

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

在写代码前理清思路

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

写出以下类主体

public class BurgersManager {
}

思考:“那么,我应该在BurgersManager类中有些CRUD操作”
写下:

public…

思考:“我应该返回什么值?目前来说void就可以”

public void addBurger(Burger burger) {
// TODO implement that later
}
public …

思考:“我应该返回被吃掉的汉堡的实例吗?还是void就可以?就像第4步那样。。。”

public void eat(Burger burger, boolean fast) {
// TODO …

告诉自己:“糟糕,咖啡时间了,我的咖啡呢。。。”
搜索,喝咖啡,和同事交谈
然后告诉自己:“回去工作吧,我刚才在做什么来着?”
我知道,你在这个例子中看到了自己,对吧?在创造性工作刚开始的时候,我们的思路有些混乱,所以当你直接开始写代码,那么代码也会很混乱。在写代码之前就考虑文档能够帮你理清思路并清除列出你要用代码实现的事。所以第一步应该是写出以下代码:

/**

此类通过提供CRUD操作来管理汉堡
采用单件模式。可以使用{@link #getInstance()}来获得这个管理器的实例。
之后可以用以下方法来调用CRUD操作:
*/
{@link #addBurger(Burger)} 用来增加汉堡,并受管理于

单件实例 ;
@作者 Thierry Wasylczenko
@版本 0.1
@since BurgerQueen 1.0
*/
public class BurgersManager {
}

这就是一个简短的例子,这个例子能够:
强迫你思考你创建的类的目的是什么
帮你确定你的需要
即使是在你休息之后也能帮你想起来你在做什么
帮助你预估还有什么是需要做的
伙计,你是在团队中开发

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

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

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

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

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

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

Responses