改善java文档的理由、建议和技巧-java开发java经验技巧

《改善java文档的理由、建议和技巧-java开发java经验技巧》由会员上传分享，免费在线阅读，更多相关内容在工程资料-天天文库。

1、改善Java文档的理由、建议和技巧-编程开发技术改善Java文档的理由、建议和技巧木文由ImportNew・Brook翻译自zeroturnaroundo欢迎加入翻译小组。转载请见文末耍求。我非常确定，作为开发人员我们都喜爱技术文档。我们喜欢阅读文档、写文档，更不用说维护文档了，我简直爱死它了！我也知道，每次你创建一个类或者一个方法，你都会想到要为此写文档。我也很确定你很享受于写文档，就像你喜欢偶尔美味的汉堡一样。但是有时候，只是有时候，你会想耍松懈一•下，也许这次就跳过文档部分。不幸的是，这种行为会很快地失控。所以在这篇文章中，我想聊聊这

2、个开发者的生活中关键但是通常被忽视并遗忘的部分。希望你会从此爱上文档，明白你的代码为什么能工作，能帮助你、伤〈的团队和使用你的软件的数不尽的用户。为什么文档很重要通常，开发者都不会忘记他们两个星期前写的代码。两个月以后甚至更长时间以后他们都会记得。即使我们保证我们从来不忘记我们写过的任何代码，写文档却有另一个理由并且更加重要。在写代码前理清思路我会举一个口己的例了：我有一个开发SlidcshowFX里一个全新特性的想法，这时我就想直接开始写代码并实现它。但我知道我不是做这项工程的唯一一个冇激情的开发者。所以我的典型行为是这样的：1.写岀以下

3、类主体publicclassBurgersManager{}2.思考：“那么，我应该在BurgersManager类中有些CRUD操作”3.写下：public…4•思考：“我应该返冋什么值？目前來说void就可以”5.publicvoidaddBurgcr(Burgerburger){//TODOimplementthatlaterpublic…6•思考：“我应该返回被吃掉的汉堡的实例吗？述是void就可以？就像第4步那样。。。”7.publicvoideat(Burgerburger,booleanfast){//TODO…&告诉口己：“

4、糟糕，咖啡时间了，我的咖啡呢。。。”9.搜索，喝咖啡，和同事交谈10.然后告诉自己：“冋去工作吧，我刚才在做什么来着？”我知道，你在这个例子中看到了自己，对吧？在创造性工作刚开始的时候，我们的思路有些混乱，所以当你直接开始写代码，那么代码也会很混乱。在写代码之前就考虑文档能够帮你理清思路并清除列出你要用代码实现的事。所以第一步应该是写岀以下代码：/***此类通过提供CRUD操作来管理汉堡*采用单件模式。可以使用{〈ahref二'http://www.jobbolc.com/members/578453495>@link#getlns

5、tance()}来获得这个管理器的实例。*之后可以用以下方法来调用CRUD操作：*/{@link#addBurger(Burger)}用来增加汉堡，并受管理J：*单件实例；*@作者ThierryWasylczenko*⑪版本0.1*@sincc〈/3>BurgerQueen1.0*/publicclassBurgersManage

6、r{)这就是一个简短的例了，这个例了能够：•强迫你思考你创建的类的目的是什么•帮你确定你的需要•即使是在你休息Z后也能帮你想起来你在做什么•帮助你预估还有什么是需要做的伙计，你是在团队中开发你也许不是在单独工作，你可能有尊敬的同事，你想和那些同事一起喝咖啡聊天。重点是，因为你喜欢他们，所以你想要帮助他们参与到你那令人兴奋的汉堡王的实现屮去。为此，最好的做法就是确定他们在读你的代码时，冇完美的文档参考。即使他们在你写代码之后的两个星期问你问题，你也能毫无犹豫地冋答他们。这就是另一个为什么文档很重要的理由：它能避免人们多次跑來问你你这复杂的算法

7、是怎样运作的，或者为什么管理器屮增加的汉堡没有同样被加到职工管理器的统计中去。在一个团队中，文档可以避免以下问题：•在工作的时候被打断，Z后难以返回继续工作；•寻找可以I叫答问题的人，因为让其他成员知道了解自己是否能够回答问题；•等待某个队员有时间回答他们的问题。•所以写文档可以帮助团队提高生产力并专注于开发。让成功更进一步这一点更加主观些。写Javadoc让我非常有成就感，因为当我再次使用我的API的时候，我写代码有文档参考，这帮我确保我没有忘记任何小细节。尽管我通常不会忘记，知道有文档在支撑我的记忆力也是件很棒的事。看到IntclliJ

8、IDEA展示我的文档让我有“嘿，看，我就像是专业的，我做的东西太棒了，我其至有文档噢”的感觉。在某些程度上的确是这样，不是吗？因为当你在使用一个lib,其中的log(String