良好的注释
关于注释有一种说法:“别给糟糕的代码加注释--重新写吧”。从这可以看出,注释不是糟糕代码的美化。注释是为某些代码加入一种描述,当代码无法明显表示你的意图时,注释就是一剂良药。但是注释是有很大的缺点。那就是程序员无法永远保持注释的更新,经常出现的情况是代码变动了,但是注释并没有随之而改。
好的注释需要遵循的原则
- 好的注释就是没有注释,让代码具有自解释的功能。
- 注释要精炼,不要废话连篇,不要太长,不要单纯的重复。
- 提供信息的注释是好注释。有的注释只是把代码翻译一下,没有指出代码的目的等有用信息。
- TODO注释也是好注释,用以提醒程序员代码的某些部分未完成。
- 对于公共的API需要提供好的Javadoc。
- 不要注释代码。注释掉的代码会给后面的人一种很重要的感觉,别人不会删除,到最后会产生大量的令人厌恶的包含注释的代码。
- 不要万物皆注释。
- 写了注释之后要时常更新。