++++++++++++

第八章：?文檔

++++++++++++


150.閱讀代碼時,?應該盡可能地利用任何能夠得到的文檔.

151.閱讀一小時代碼所得到的信息只不過相當于閱讀一分鐘文檔.

152.使用系統的規格說明文檔,?了解所閱讀代碼的運行環境.

153.軟件需求規格說明是閱讀和評估代碼的基準.

154.可以將系統的設計規格說明作為認知代碼結構的路線圖,?閱讀具體代碼的指引.

155.測試規格說明文檔為我們提供可以用來對代碼進行預演的數據.

156.在接觸一個未知系統時,?功能性的描述和用戶指南可以提供重要的背景信息,從而更
好地理解閱讀的代碼所處的上下文.

157.從用戶參考手冊中,?我們可以快速地獲取,?應用程序在外觀與邏輯上的背景知識,?
從管理員手冊中可以得知代碼的接口|文件格式和錯誤消

息的詳細信息.

158.利用文檔可以快捷地獲取系統的概況,?了解提供特定特性的代碼.

159.文檔經常能夠反映和提示出系統的底層結構.

160.文檔有助于理解復雜的算法和數據結構.

161.算法的文字描述能夠使不透明(晦澀,?難以理解)的代碼變得可以理解.

162.文檔常常能夠闡明源代碼中標識符的含義.

163.文檔能夠提供非功能性需求背后的理論基礎.

164.文檔還會說明內部編程接口.

165.由于文檔很少像實際的程序代碼那樣進行測試,?并受人關注,?所以它常常可能存在
錯誤|不完整或過時.

166.文檔也提供測試用例,?以及實際應用的例子.

167.文檔常常還會包括已知的實現問題或bug.

168.環境中已知的缺點一般都會記錄在源代碼中.

169.文檔的變更能夠標出那些故障點.

170.對同一段源代碼重復或互相沖突的更改,?常常表示存在根本性的設計缺陷,?從而使
得維護人員需要用一系列的修補程序來修復.

171.相似的修復應用到源代碼的不同部分,?常常表示一種易犯的錯誤或疏忽,?它們同樣
可能會在其他地方存在.

172.文檔常常會提供不恰當的信息,?誤導我們對源代碼的理解.

173.要警惕那些未歸檔的特性:?將每個實例歸類為合理|疏忽或有害,?相應地決定是否應
該修復代碼或文檔.

174.有時,?文檔在描述系統時,?并非按照已完成的實現,?而是系統應該的樣子或將來的
實現.

175.在源代碼文檔中,?單詞gork的意思一般是指”理解”.

176.如果未知的或特殊用法的單詞阻礙了對代碼的理解,?可以試著在文檔的術語表(如果
存在的話)|New?Hacker’s?Dictionary[Ray96]|或在

Web搜索引擎中查找它們.

177.總是要以批判的態度來看待文檔,?注意非傳統的來源,?比如注釋|標準|出版物|測試
用例|郵件列表|新聞組|修訂日志|問題跟蹤數據庫|營

銷材料|源代碼本身.

178.總是要以批判的態度來看待文檔;?由于文檔永遠不會執行,?對文檔的測試和正式復
查也很少達到對代碼的同樣水平,?所以文檔常常會誤導

讀者,?或者完全錯誤.

179.對于那些有缺陷的代碼,?我們可以從中推斷出它的真實意圖.

180.在閱讀大型系統的文檔時,?首先要熟悉文檔的總體結構和約定.

181.在對付體積龐大的文檔時,?可以使用工具,?或將文本輸出到高品質輸出設備上,?比
如激光打印機,?來提高閱讀的效率.