在很多时候我们是希望看到注释的,而且在很多糟糕的代码或者项目中只有看了代码才能知道那成百上千行的代码到底做了什么。不过还是请注意,有时候注释反而会让我们对代码更加误解,我只是说:有时候,(在很小一部分的时候),本人就出现过这样的问题。
在很多时候我习惯上是先写代码,写完代码之后开始对这个方法写上注释,在一行代码上写上注释,就觉得自己已经对代码交代完了,可以进行下一个任务了。但其实很多时候这样有几个小问题:
1、让我们误认为自己对这段代码已经负责了,但是殊不知如果我们的命名糟糕,逻辑糟糕,那么即便是写上注释仍然避免不了其他程序员的吐槽,开个玩笑(你会经常听到的);关键是这样会让我们误认为自己已经进步了,因为自己会在心里给自己打一个分,而这个加分项不在代码上,而是在注释上,所以别人看了代码吐槽的时候我们仍然可以理直气壮的说:你不看注释的嘛?
2、承接上一点:让我们关注注释,而对业务逻辑,参数命名,方法命名等最能够能代码自己说话的地方不在那么关心,为什么?因为我们会下意识的给自己一个台阶:因为有注释。
3、请注意,我自己在很糟糕的代码旁边写的注释也一定不会很简洁或者是漂亮,或者是即便上面有注释,但是代码需要修改的地方,我仍然也懒得修改原作者写的那段注释,不知道你有没有这样做过。OK,可想而知,这样下去,重构是必然的,不是一小部分,而是大部分代码;
建议的注释:
类上面的注释:1、
Description(这个类的作用)
2、版权
3、作者
4、版本
方法上的注释:
1、方法说明
2、输入参数
3、输出参数
4、异常
5、如果和类的创建者作者不一样,建议加上自己的名字
例子:
- /**
- * @author dengsilinming
- * @date Sep 18, 2012
- * @time 9:38:25 AM
- * @param args
- * @throws IOException
- * @throws HttpException
- * @description
- */
好的例子如下:
好了,写到这,大家应该已经明白我的意思了:不是不要注释,而是尽可能让你的代码自己说话,注释不可少,而且是必须,但是最重要的是代码自己会说话。
下面让我用一句话来结束:
不要注释坏代码——重写吧。——Brian W. Kernighan and P. J. Plaugher