飞云小侠的个人博客

我的首页 / 文章归档 / 资源中心 / 网站链接 / 博客首页 / 管理面板 /

« 平台管理程序的首页 | Main | 使用FreeMarker-IDE,辅助提示WebWork的Tag语法 »

JavaDoc/代码注释乱弹

2006/05/10,17:48

多写点JavaDoc,代码文档吧!

如果要问为什么写JavaDoc和代码里面的注释,那么就应该明白这些东西是给谁看的.

我认为它们是给下列人看得:

1.你自己
过3个月后,你还能看懂自己的代码吗?一年后哪?

当然除了JavaDoc之外,方法名,类名以及组织结构都要简单明了,让人容易看懂

2.合作者
很多人都觉得这么简单,这还看不懂吗? 其实,这些代码是你写的,你当然觉得简单了
需要记住:每个人的思路都不一样,自己的思路可能在不同阶段也不一样

写一些JavaDoc和注释也可以让别人了解你做了什么,修改了什么,以及为什么要这么做,例如"修改了XX-55 错误","增加了某某"功能

记得一个有趣的故事说一个新近接手一个程序的程序员,想改进项目,看到很多代码觉得没啥用途,而且罗嗦冗肿,就是就干掉了那些代码. 可是经过一些时间,才知道那些代码是用来修正一些Server的不兼容的错误的,于是又改回来.

其实这个故事很多人都笑话这个新来的程序员,但是我更认为这个责任在原来的程序员,你为什么不写点注释说明这段代码是干什么的! 在WebWork的代码里,我们会看到一些注释,说明代码是用来修正WebLogic,Resin等的不兼容的情况,这就是对应的正确做法.

3.其他使用你的程序/代码的人

对于从来没有涉猎过某些领域的开发者,优秀的JavaDoc能让他领悟到这个程序是做什么的,以及必须的步骤,操作的流程,以及一些注意事项.

一个发布后的程序或者工具类,必然包含很多文件,阅读源码肯定能更加透彻理解作者的思路,熟悉此领域的人也能明白你的意图.但是对于从来没有涉猎此领域的开发者,可能根本看不懂你的源码.例如让我看Eclipse插件的源码,总是很糊涂.特别是那些一行注释都没有的程序,真是7456.

我认为,非常多的开发人员是没有时间来看源码的,
1.因为一般很多东西不是核心技术,没必要彻底了解,只是拿来使用罢了.
2.有的开发人员也根本没有看源码的习惯,一般看看文档,看看例子就能跑起来
3.为什么要看源码哪?又不是什么"精华". :P
4.lib库,工具栏,框架如此之多,我们了解它的第一步就是看文档,如果参考手册或者开发者指南写的非常详细,哪为什么JavaDoc就不能写的更好一点哪!当然了,很多东西根本没有参考手册/指南.

那么应该如何编写JavaDoc和注释哪
1.输出后,读者阅读后,能明白类是干什么的,如果有操作流程,应该有示例.如果有特殊注意事项,一定要注明
2.方法的参数如果有特殊需要,一定要注明参数应该是什么要求.例如一个List的参数,应该让使用者明白传入的List应该包含什么类型的数据
3.改动说明一定要注明,当然不一定是JavaDoc的格式了
4.多个版本发布的类库要写一些Since,否则版本不对,无法使用那就郁闷
5.复杂的方法写一些适当的注释,让人明白操作的流程,变量的含义

最近想研究一下FreeMarker-IDE插件,结果一行注释都没有,我这个郁闷啊...70多个文件...不想看了

我个人写的代码里面注释很多,一般都能明白代码是干什么的...很多人根本没有写注释的习惯.

我觉得代码里面至少要有10%的注释或者更多!

没有文档,没有JavaDoc,没有注释,别人如何了解你的东西,如何维护你的代码哪...

如果你看别人的源码看不懂,那么你自己写代码的时候就多些点文档吧...