32章 Self-Documenting Code读书笔记

看完这章我有一个最大的感受，写代码就像写一本书一样。代码就像书中的文字，而注释就像书的目录一样。有了目录查找书中的类容就方便很多，要修改代码也很容易。这当然也和代码的组织或者说书的排版有密切关系。这章的重点是代码注释，对我来说是一个很头痛的问题，我之前的代码注释总觉得写的不很科学，不如直接看代码。看了《代码大全》如拨开云雾见青天，豁然开朗。首先作者将代码注释分了一下类，如下有五类：

Repeat of code

有时注释仅仅是代码的重复，只不过用自然语言说了出来。这是最差的注释，要了等于没有。

Explanation of the code

代码的注释有时只是对复杂代码的解释，这时候注释的代码比较难懂，或者用了什么小技巧让代码晦涩难懂。如果一个代码已经复杂到必须看注释才能读懂的话还是把代码重写好了，

Marker in the code

Marker comment 只是代码中的一个标记，不应该留在代码中。这是一个标记说明开发人员的代码还没有开发完成。比如这样的代码：

return NULL; // ****** NOT DONE! FIX BEFORE RELEASE!!!

这样的代码还是要避免的，想想debug半天结果得出这样的结果，你肯定想摧残下下这段代码即注释的人。

Summary of the code

注释是代码的总结应该算很好的，通过一句或者两句话总结了一个函数的功能一个类的功能，当你看代码时，只要看一眼便知道是它的作用，这样你查找修改函数都比较方便。

Description of the code’s intent

注释作为描述代码的意图，站在了问题的角度，而不是解决方案的角度。不过个人认为对于看代码的人来说这也是不错的，至少我明白了代码在做什么。例如：

-- get current employee information

就是一个描述意图的注释，但是

-- update employeeRecord object

是针对一个解决方案的思路来注释代码。

具体到写代码中注释还是要对代码的总结或者描述代码的意图，这样读代码的人比较轻松。注释就像一本书的目录一样，读到了感兴趣的章节就继续深入读吧。具体如何给代码注释，用什么样的风格，每个人都有自己的一套。多看看优秀的代码就行了，但是思想应该是一样的，写代码就像写书一样，一定要结构清晰，布局合理。