你写注释吗？

1、注释（包括 Javadoc）是代码的重要组成部分！为什么？因为代码是给人看的，不是给机器看的。

2、非 Javadoc 部分出现大段注释的话，说明作者非常脑残。把代码写清楚点会死啊。

3、非 Javadoc 注释稍微点缀一下即可。比如 double RATE = 0.2，加个注释说明一下为什么是这个值，不然的话过半年作者自己都会不记得了。

老实说“ double RATE = 0.2”如果不是公用变量。而是随便在方法中这么写，我是要骂人的。
而且这个RATE是什么的RATE？不能多写几个字母写清楚嘛。难道非要加注释？

多写几个也未必有用啊，难道要你写 RESERVE_FOR_BETTER_PERFORMANCE_AND_CAN_BE_INCREASED_IF_NEEDED？

最好的注释是代码，印象中是uncle Bob说的。
但是好像kent beck说最好的文档是代码。
所以，嘿嘿。
写代码这事情不能细说啊~

文字的东西很不可靠，因为无法测试，无法验证。是否同步就显得很不好验证。
比如你写了个注释，别人在这之后修改了代码，但是注释忘记了。测试也通过了，运行和部署都没有问题。但是过了之后，忽然出现了bug，你跟着注释一看，这块不应该有问题，放过的机会非常大。
而且我这个人私下认为，一个人写不好代码，希望他们写的注释和文档要能好，也是有点奢望。反正我见到的主要是能写好代码的，也能写好注释和文档，只不过他们不愿意写。
另外一个更加麻烦的事情是，以后SCM工具和CASE之类的东西，往往喜欢在注释里面添加点什么，而有的部署工具也喜欢在代码里面填东西。遇到这种情况十分难以控制最终究竟会发生什么问题。
同时你还会发现，自然文字的东西往往有多义性，特别是别人看的时候，产生错误理解的可能性很大。如果那个人刚好是一个跟上面这些不喜欢动脑筋，也不喜欢查资料的人所类似，那么后果就十分的不能被控制。
所以我十分反感在完成的代码中出现人手工写的和维护的注释。今天我再次重复一遍，但愿这个是最后一次了。

恰恰相反，自然语言的表达能力比JAVA语言的表义能力强得多。看到一个JAVA方法名，我们可能要猜它的意义；但看到一条英语句子，我们就会很明确了。 举个例子，在apache的StringUtils类中，如果你不看注释，你知道defaultString()是什么意思吗？你能百分百确定 isEmpty()和 isBlank()的区别吗？ 除了空格和制表符算一种“Blank”，回车换行算不算"Blank"呢？

Whatever they say, they say.

注释是对一个接口的说明，也就是说可以充当部分“契约”

如果我们不写注释
   1. 仅凭方法名和参数名未必能猜到详尽的契约。比如哪些参数Nullabe，这个API在整个框架中的作用等等。有个典型的例子就是java.util.Set。它有个约定就是它的元素应该实现hashCode()方法和equals()方法，Set将基于这两个方法来比较两个元素是否相等。

   2. 有人说看看代码细节也能明白方法的契约。但我只是要调用一个接口，我把你当一个黑盒，凭什么要求我花时间去看你的代码实现？

看测试。
所以说“源代码是最好的文档”还不全面，应该是“源代码及其测试是最好的文档”。

恰恰相反，自然语言的表达能力比JAVA语言的表义能力强得多。看到一个JAVA方法名，我们可能要猜它的意义；但看到一条英语句子，我们就会很明确了。 举个例子，在apache的StringUtils类中，如果你不看注释，你知道defaultString()是什么意思吗？你能百分百确定 isEmpty()和 isBlank()的区别吗？ 除了空格和制表符算一种“Blank”，回车换行算不算"Blank"呢？