我非常确定，作为开发人员我们都喜爱技术文档。我们喜欢阅读文档、写文档，更不用说维护文档了，我简直爱死它了！
我也知道，每次你创建一个类或者一个方法，你都会想到要为此写文档。我也很确定你很享受于写文档，就像你喜欢偶尔美味的汉堡一样。但是有时候，只是有时候，你会想要松懈一下，也许这次就跳过文档部分。不幸的是，这种行为会很快地失控。
为什么文档很重要
通常，开发者都不会忘记他们两个星期前写的代码。两个月以后甚至更长时间以后他们都会记得。即使我们保证我们从来不忘记我们写过的任何代码，写文档却有另一个理由并且更加重要。
在写代码前理清思路
我会举一个自己的例子：我有一个开发SlideshowFX里一个全新特性的想法，这时我就想直接开始写代码并实现它。但我知道我不是做这项工程的唯一一个有激情的开发者。所以我的典型行为是这样的：
1.写出以下类主体
publicclassBurgersManager{
}
2.思考：“那么，我应该在BurgersManager类中有些CRUD操作”
3.写下：
public…
4.思考：“我应该返回什么值？目前来说void就可以”
5.publicvoidaddBurger(Burgerburger){
//TODOimplementthatlater
}
public…
6.思考：“我应该返回被吃掉的汉堡的实例吗？还是void就可以？就像第4步那样。。。”
7.publicvoideat(Burgerburger,booleanfast){
//TODO…
8.告诉自己：“糟糕，咖啡时间了，我的咖啡呢。。。”
9.搜索，喝咖啡，和同事交谈
10.然后告诉自己：“回去工作吧，我刚才在做什么来着？”
我知道，你在这个例子中看到了自己，对吧？在创造性工作刚开始的时候，我们的思路有些混乱，所以当你直接开始写代码，那么代码也会很混乱。在写代码之前就考虑文档能够帮你理清思路并清除列出你要用代码实现的事。所以第一步应该是写出以下代码：
/**
*此类通过提供CRUD操作来管理汉堡
*采用单件模式。可以使用{<ahref='http://www.jobbole.com/members/57845349'>@link</a>#getInstance()}来获得这个管理器的实例。
*之后可以用以下方法来调用CRUD操作：
*/
{<ahref='http://www.jobbole.com/members/57845349'>@link</a>#addBurger(Burger)}用来增加汉堡，并受管理于
*单件实例;
*@作者ThierryWasylczenko
*@版本0.1
*<ahref='http://www.jobbole.com/members/chchxinxinjun'>@since</a>BurgerQueen1.0
*/
publicclassBurgersManager{
}
这就是一个简短的例子，这个例子能够：
强迫你思考你创建的类的目的是什么
帮你确定你的需要
即使是在你休息之后也能帮你想起来你在做什么
帮助你预估还有什么是需要做的
伙计，你是在团队中开发
你也许不是在单独工作，你可能有尊敬的同事，你想和那些同事一起喝咖啡聊天。重点是，因为你喜欢他们，所以你想要帮助他们参与到你那令人兴奋的汉堡王的实现中去。为此，最好的做法就是确定他们在读你的代码时，有完美的文档参考。即使他们在你写代码之后的两个星期问你问题，你也能毫无犹豫地回答他们。
