核對表（自說明代碼）

• 你的類接口體現出某種一致的抽象嗎？
• 你的類名有意義嗎，能表明其中心意圖嗎？
• 你的類接凵對於如何使用該類顯而易見嗎？
• 你的類接囗能抽象到不需考慮其實現過程嗎？能把類看成是黑盒嗎？

子程序

• 你的每個子程序名都能準確地指示該子程序確切幹些什麽嗎？
• 你的各子程序的任務明確嗎？
• 若各子程序中自成一體後更有用，你都將其各自獨立出來了嗎？
• 每個子程序的接口都清晰明了嗎？

數據名

• 類型名描述有助於說明數據聲明嗎？
• 你的變量名有意義嗎？
• 變量只用在其名字所代表意義的場合嗎？
• 你的循環變量名能給出更多信息，而不是i、j、k之類的嗎？
• 你用了名字有意義的枚舉類型，而非臨時拼湊的標識或者布爾變量嗎？
• 用具名常量代替神秘數值或者字符串了嗎？
• 你的命名規範能區分類型名、枚舉類型、具名常量、局部變量、類變量以及全局變量嗎？

數據組織

• 你根據編程清晰的需要，使用了額外變量來提高清晰度嗎？
• 你對某變量的引用集中嗎？
• 數據類型簡化到了最低復雜度嗎？
• 你是通過抽象訪問子程序（抽象數據類型）來訪問復雜數據嗎？

控制

• 代碼中的正常執行路徑很清晰嗎？
• 相關語句放在一起了嗎？
• 相對獨立的語句組打包為子程序了嗎？
• 正常情況的處理位於“語句之後，而非在else子句中嗎？
• 控制結構簡單明了，以使復雜度最低嗎？
• 每個循環完成且僅完成一個功能，是像定義良好的子程序那麽做嗎？
• 嵌套層次是最少嗎？
• 邏輯表達式通過額外添加布爾變量、布爾函數和功能表簡化了嗎？

布局

• 程序的布局能表現出其邏輯結構嗎？

設計

• 代碼直截了當嗎？是不是避免了自作聰明或新花樣？
• 實現細節盡可能隱藏了嗎？
• 程序是盡可能采用問題領域的術語，而非按照計算機科學或者編程語言的術語編寫的嗎？

核對表（好的註釋技術）

一般問題

• 別人拿起你的代碼就能立刻明白其意嗎？
• 你的註釋是在解釋代碼用意，或概括代碼在做什麽，而非簡單重復代碼
• 采用了偽代碼編程法來減少註釋時間嗎？
• 是重寫有玄機的代碼，而非為其做註釋嗎？
• 你的註釋能否同代碼一起更新？
• 註釋清楚正確嗎？
• 你的註釋風格便於修改註釋嗎？

語旬和段落

• 代碼避免用行尾註釋了嗎？
• 註釋是著力說明為什麽而非怎麽樣嗎？
• 註釋為將要閱讀代碼的人們做好準備了嗎？
• 每個註釋都其用處嗎？刪掉抑或改進了多余的、無關緊要的或隨意的註釋沒有？
• 是否註釋了代碼的非常規之處？
• 避免使用用縮略語了嗎？
• 主次註釋區別明顯嗎？
• 含錯代碼和未公開的代碼特性有註釋嗎？

數據聲明

• 對數據聲明的註釋說明了數值單位嗎？
• 數值數據的取值範圍註釋出來了嗎？
• 註釋出了編碼含義嗎？
• 對輸入數據的限制有註釋嗎？
• 對位標誌做註釋了嗎？
• 在各全局變量聲明的地方對其做註釋了嗎？
• 各全局變量是通過命名規範、註釋（或者兩者兼用）來標識其意義嗎？
• 神秘數值是否以具名常量或變量代替，而非只是標註之？

控制結構

• 控制語句都註釋了嗎？
• 冗長或者復雜的控制結構結尾處有註釋嗎？抑或可能的話，簡化之從而省去註釋了嗎？

子程序

• 各子程序的意圖都註釋出了嗎？
• 子程序的其他有關情況（諸如輸入輸出數據、接口假設、局限性、糾錯、全局效果和算法來源）都註釋出來了嗎？

文件、類和程序

• 程序有簡短的文檔（就像在“以書本為範例”中說明的那樣）給出程序組織的概述嗎？
• 每個文件的用途都有說明嗎？
• 作者姓名、email及電話號碼在代碼清單中都有嗎？

要點

• 該不該註釋是個需要認真對待的問題。差勁的註釋只會浪費時間，幫倒忙；好的註釋才有價值。
  +源代碼應當含有程序大部分的關鍵信息。只要程序依然在用，源代碼比其他資料都能保持更新，故而將重要信息融入代碼是很有用處的。
• 好代碼本身就是最好的說明。如果代碼太糟，需要大量註釋，應先試著改進代碼，直至無須過多註釋為止。
• 註釋應說出代碼無法說出的東西一一一例如概述或用意等信息。
• 有的註釋風格需要許多重復性勞動，應舍棄之，改用易於維護的註釋風格。

《代碼大全》閱讀筆記-32-自說明代碼