『思考』为什么老外的注释和文档普遍比国人好得多？欢迎讨论

0 views

Skip to first unread message

李建鹤

unread,

Dec 13, 2008, 8:46:55 AM12/13/08

to java-dream

注释和文档是程序质量的一个极其重要的部分，怎么强调也不为过

大家可能都有这样的体验：看老外的程序是一种享受，看(维护)国人的程序是一种苦差。除了编码水平的问题，注释文档是一个明显的区别：老外的注释详尽，常常是注释多于程序本身，如jdk的一些类，接口；国人的程序往往注释极少，甚至就没有。原因何在？

我们都知道注释文档的重要性，但好象又没有受到约束。很多公司提倡的代码的互测和自测只是说说而已，没有从制度上落到实处。要保证产品开发实施的延续性，这些极其重要。关于注释和文档，可能你心里很清楚(过个一年半载你不一定会清楚)，但能否清晰地表达出来，落实到字面上，这是很需要花精力的事，也是很锻炼人的事，你一定要用心去做才可能做好。对于做产品，很多时候注释和文档的重要性要大于程序本身。你有没有用全心做这件事，有没有站在看你文档和注释的人员的角度去思考这个问题，而不是仅仅写完代码实现功能了事，与你的个人素质和做事严谨性密切相关，这主要靠个人的修养和自觉(扪心自问，我有没有尽力)，但也应该从制度上督促和鼓励，使得用心踏踏实实地做这样的事的人得到认同。

时时问一句，我有没有为一起做这件事和后续做这件事的人着想，而不是仅仅狭隘地为自己着想，为赶进度而匆匆实现功能了事。