关于代码注释的危害

Question

在github的LTP项目(一个linux内核测试项目)的文档看到这么一句话不很理解，关于代码注释的危害.

Comments can sometimes save you day but they can easily do more harm than good. There has been several cases where comments and actual implementation were drifting slowly apart which yielded into API misuses and hard to find bugs. Remember there is only one thing worse than no documentation, wrong documentation.

我印象中不是鼓励大家进行代码注释嘛？这里面说Comments more harm than good 。
原因 ：comments and actual implementation were drifting slowly apart
结果：API misuses and hard to find bugs.

因为自己英语不太好，用翻译软件也觉得生硬， 注释和实际实现之间的距离很近？导致API滥用和未知的错误？

请教下， 这几句到底是什么含义？API滥用以及未知的错误 又可能 会导致什么危害？ 能举个具体的例子就更为感谢。

原文地址：https://github.com/linux-test...

Answer 1

比注释更有用的是规范的命名和单一职责

Answer 2

comments and actual implementation were drifting slowly apart
注释与实现之间漂移得渐行渐远
API misuses and hard to find bugs.
Api 误用而难察暗坑儿.

Answer 3

个人觉得最后一句是点睛之笔，Remember there is only one thing worse than no documentation, wrong documentation. 就是错误的文档危害要比没有文档大的多，错误文档导致错误使用，代码还难以定位bug

Answer 4

意思就是注释这个东西虽然很好，很多时候能够让你明白这个段代码的意图，但是有些注释（我猜指的是错误或者说不专业的注释）也会很容易让你理解错API的意图。就跟阅读理解一样，不同人可能理解的意思不同。理解错了你可能就用错了，并且此类的bug很难寻找。

就好像你理解这段翻译，实际上也要从文章上下文出发去理解。
还有就是，没必要太钻牛角尖，纠结翻译，理解大概意思就好了。