《代码整洁之道》读书笔记4

第4章主要是关于注释的内容。

在做这章笔记之前，有个问题应该事先讨论一下，注释是否有存在的必要，之前也看到过不少人讨论这个，其实个人感觉这个没有什么讨论的必要，因为不用注释的支持者的原因无外乎就是，注释应该用标准的代码来表示，坏的注释会导致错误。这些原因看似正确，也确实正确，但是很少有人做到，所以并没有太多的意义，注释是无可取代的，当然坏的注释确实不如没有注释。

下列是好的注释的情况：

1. 法律信息，也就是copyright，这个在专业软件必须有的，也建议大家去了解常用的copyright。

2. 提供信息的注释，当然如果有合理的命名，这样的注释可以省略，对自己命名没信心的人（比如我）还是老实的写注释吧。

3. 提供原因的注释，也就是所谓的对whyXX，或者XXXto类型的注释。

4. 阐释性的注释，一般是用不能修改的库时进行说明，或者作者为自己使用的语法糖加的注释。

5. 警告性的注释，虽然作者认可这种注释，但是我感觉用assert等方式来确保更合适。

6. TODO注释，这个很好用，发布之前一定要好好检查一下所有的TODO的注释。

7. 强调性注释，一般放到重要代码的部分，注意更新代码时看看注释用不用修改。

8. JavaDoc，嗯，Java的不懂，不过估计doxygen之类的注释都是可以的。

下边就是坏的注释了：

1. 只有自己看的懂的注释，不明显的注释，对于注释的可读性，需要像命名和代码一样要求，那种就自己看的懂的注释，时间长了，自己也看不懂了，囧...

2. 多余的注释，废话的注释，也就是不用看就知道的注释，记住，不要为了注释而注释。

3. 误导的注释，其实这类就是错误的注释了，这类注释可能给调试带来不少麻烦，写这类注释不如没有注释，这类注释很多就是因为更新代码没更新注释导致的。

4. 规矩性的注释，重来没有每个函数都要有注释，每个变量都要注释的脑残规矩。

5. 日志式注释，署名注释，删了这些脑残的注释，学习使用源码控制系统去吧，少年。

6. 可以用函数或者变量取代的注释，可以取代的尽量取代，但是不是全部取代，最开始说过了。

7. 标记式，临时式注释，比如-----，XXXX这些注释，有时确实很方便，但是千万要记得完成后及时清理。

8. 括号后面的注释，比如//end while这类注释，说实话，认为这个注释不好的原因就是应该写更短的函数，但是写更短函数的可实施性问题，咱们之前讨论了，个人感觉不要这类注释的原因主要是很多IDE都有相应功能。

9. 注释掉的代码。如果不是临时的，代码要删掉，不是注释掉，及时是临时的，也尽量不用注释，用宏更好，什么？你想找原来的代码怎么办，告诉你去学源码控制系统了。

10. HTML，XML等注释，如果这类注释是某些工具需要的，那么就让工具去干这些，而不是程序员。

11. 函数头的注释，这个再强调一点，没有任何规矩说明每个函数必须有函数头，短的函数用合适的命名就行了。

12.不如不是打算公用或者开源，那么加javadoc或者doxygen的注释，那完全是蛋疼的行为了，书中用到了个很形象的说法，”八股程序'。