第三十二章 自說明代碼

外部文檔

• 單元開發文件夾；
  • 是一種非正式文檔，其中包含了供開發者在變成期間使用的記錄；
• 詳細設計文檔；
  • 是低層次設計文檔，描述在類層或子程序層的設計決定，曾考慮過其餘方案，以及採用所選方案的理由。

編程風格文檔

覈對表：自說明代碼

類

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

子程序

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

數據名

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

數據組織

• [ ] 你根據編程清晰的須要，使用了額外變量來提升清晰度嗎？
• [ ] 你對某變量的引用集中嗎？
• [ ] 數據類型簡化到了最低複雜度嗎？
• [ ] 你是經過抽象訪問子程序來訪問複雜數據嗎？

控制

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

佈局

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

設計

• [ ] 代碼直截了當嗎？是否是避免了自做聰明或新花樣？
• [ ] 實現細節儘量隱藏了嗎？
• [ ] 程序是儘量採用問題領域的術語，而非按照計算機科學或者編程語言的術語編寫的嗎？

高效註釋之關鍵

註釋種類

• 重複代碼；
• 解釋代碼；
• 代碼標記；
• 概述代碼；
• 代碼意圖說明；
• 傳達代碼沒法表述的信息；

高效註釋

• 採用不會打斷或抑制修改的註釋風格；
• 用僞代碼編程法減小注釋時間；
• 將註釋集成到你的開發風格中；
• 性能不是逃避註釋的好藉口。

註釋技術

註釋單行

對於好的代碼，不多須要註釋單條語句。要註釋一行代碼，有兩種可能的理由：

1. 該行代碼太複雜，於是須要解釋；
2. 改行語句出過錯，你想記下這個錯。

關於單行註釋，下面有些指導原則：

• 不要隨意添加無關注釋；

行尾註釋及其問題

• 不要對單行代碼作行尾註釋；
• 不要對多行代碼作行尾註釋。

什麼時候使用行尾註釋

• 行尾註釋用於數據聲明；
• 避免用行尾註釋存放維護註記；
• 用行尾註釋標記塊尾。

註釋代碼段

• 註釋應表達代碼的意圖；
• 代碼自己應盡力作好說明；
• 註釋代碼段時應注重「爲什麼作」而不是「怎麼作」；
• 用註釋爲後面的內容作鋪墊；
• 讓每一個註釋都有用；
• 說明很是規作法；
• 別用縮略語；
• 將主次註釋區分開；
• 錯誤或語言環境獨特色都要加註釋；
• 給出違背良好編程風格的理由；
• 不要註釋投機取巧的代碼，應重寫之。

註釋數據聲明

• 註釋數值單位；
• 對數值的容許範圍給出註釋；
• 註釋編碼含義；
• 註釋對輸入數據的限制；
• 註釋「位標誌」；
• 將與變量有關的註釋經過變量名關聯起來；
• 註釋全局數據。

註釋控制結構

• 應在每一個if、case、循環或者代碼段前面加上註釋；
• 應在每一個控制結構後加上註釋；
• 將循環結束處的註釋堪稱時代碼太複雜的徵兆。

註釋子程序

• 註釋應靠近其說明的代碼；
• 在子程序上部用一兩句話說明之；
• 在聲明參數處註釋這些參數；
• 利用諸如Javadoc之類的代碼說明工具；
• 分清輸入和輸出數據；
• 註釋接口假設；
• 對子程序的侷限性做註釋；
• 說明子程序的全局效果；
• 記錄所用算法的來源；
• 用註釋標記程序的各部分；

註釋類、文件和程序

標註類的通常原則

• 說明該類的設計方法；
• 說明侷限性、用法假設等；
• 註釋類接口；
• 不要在類接口處說明實現細節。

註釋文件的通常原則

• 說明各文件的意圖和內容；
• 將姓名、電子郵件及電話號碼放到註釋塊中；
• 包含把版本控制標記；
• 請在註釋塊中包含法律通告；
• 將文件命名爲與其內容相關的名字。

程序註釋以書本爲範例

檢查表：好的註釋技術

通常問題

• [ ] 別人拿起你的代碼能馬上明白其意嗎？
• [ ] 你的註釋是在解釋代碼用意，或歸納代碼在作什麼，而非簡單重複代碼嗎？
• [ ] 採用了僞代碼編程來減小注釋時間嗎？
• [ ] 是重寫有玄機的代碼，而非爲其作註釋嗎？
• [ ] 你的註釋可否同代碼一塊兒更新？
• [ ] 註釋清楚正確嗎？
• [ ] 你的註釋風格便於修改註釋嗎？

語句和段落

• [ ] 代碼避免用行尾註釋了嗎？
• [ ] 註釋是着力說明爲何而非怎麼樣嗎？
• [ ] 每一個註釋爲將要閱讀代碼的人們都作好準備了嗎？
• [ ] 每一個註釋都有其用處嗎？刪掉抑或改進了多餘的、可有可無的或隨意的註釋沒有？
• [ ] 是否註釋了代碼的很是規之處？
• [ ] 避免使用縮略語了嗎？
• [ ] 主次註釋區別明顯了嗎？
• [ ] 含錯代碼和未公開的代碼特性有註釋嗎？

數據聲明

• [ ] 對數據聲明的註釋說明了數值單位嗎？
• [ ] 數值數據的取值範圍註釋出來了嗎？
• [ ] 註釋出了編碼含義嗎？
• [ ] 對輸入數據的限制有註釋嗎？
• [ ] 對位標誌作註釋了嗎？
• [ ] 在各全局變量聲明的地方對其作註釋了嗎？
• [ ] 各全局變量是經過命名規範、註釋來標識其意義嗎？
• [ ] 神祕數值是否以具名常量或變量代替，而非指示標註之？

控制結構

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

子程序

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

文件、類和程序

• [ ] 程序有簡短的文檔給出程序的組織概述嗎？
• [ ] 每一個文件的用途都有說明嗎？
• [ ] 做者姓名、email及電話好嗎在代碼清單中都有嗎？

要點

• 該不應註釋是個須要認真對待的問題。差勁的註釋指揮浪費時間，幫倒忙；好的註釋纔有價值；
• 源代碼應當含有程序大部分的關鍵信息。只要程序依然在用，源代碼比其餘資料都能保持更新，故而將重要信息融入diamagnetic是頗有用處的；
• 好代碼自己就是最好的說明。若是代碼太糟，須要大量註釋，應先試着改進代碼，直至無需過多註釋爲止；
• 註釋應該說出代碼沒法說出的東西——例如概述或用意等信息；
• 有的註釋風格須要許多重複性勞動，應捨棄之，改用易於維護的註釋風格。