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

是針對一個解決方案的思路來注釋代碼。

具體到寫代碼中注釋還是要對代碼的總結或者描述代碼的意圖，這樣讀代碼的人比較輕鬆。注釋就像一本書的目錄一樣，讀到了感興趣的章節就繼續深入讀吧。具體如何給代碼注釋，用什麼樣的風格，每個人都有自己的一套。多看看優秀的代碼就行了，但是思想應該是一樣的，寫代碼就像寫書一樣，一定要結構清晰，布局合理。