接前文,我们继续分析OpenWnn的注释问题
1. 为了注释而注释
严重程度:中
注释就是把方法或者变量的名称再重写一遍,这种工作纯属是浪费时间,可以不用花费这种工时。
/** Current key-mode */ protected int mCurrentKeyMode;
这种情况在OpenWnn中特别多。
2. 啰嗦的注释
严重程度:低
本来可以很短就能够写完的注释,却要写很长的注释,结果也没有因为写的长对于理解产生有益的帮助。
这种情况在OpenWnn中非常少。
3. 步步皆注释
严重程度:中
这种情况会拉开代码间距,使代码变得不再流畅。
这种情况在OpenWnn中也非常少。
4.缺少注释
严重程度:重
并非所有的代码都需要注释,也并非所有的类都需要注释,我们主张代码应该是自表达的,应该是不怎么需要注释的,但是对于难以理解的内容如果不书写注释,那么对于读者(包括几个月之后的作者自己)来说,无疑是一种挑战。
Composing类的数据存储方式以及Cursor和EditText中的Composing之间的关系没有相应的设计资料单就从跟踪数据来也非常难以理解。这个类的数据存储方式就应该进行注释,但是却没有进行注释。以致于怎么也难以理解其中的一些算法。
5.错误的注释
严重程度:重
注释本身的内容是错误的,误导读者。这种注释有不如无,当然,视内容的错误程度不同其影响也是不同的。
/** Thread for updating the candidates view */ private void updatePrediction() {
这段代码并没有任何单独的线程处理。
6.JavaDoc注释不当
KanaConverter的类注释中的版权声明就属于多余的JavaDoc注释。