Posted on 2006-06-26 22:51
mahudu@cppblog 閱讀(165)
評論(0) 編輯 收藏 引用 所屬分類:
Programming
???
++++++++++++
第八章：?文檔
++++++++++++
150.閱讀代碼時,?應(yīng)該盡可能地利用任何能夠得到的文檔.
151.閱讀一小時代碼所得到的信息只不過相當(dāng)于閱讀一分鐘文檔.
152.使用系統(tǒng)的規(guī)格說明文檔,?了解所閱讀代碼的運行環(huán)境.
153.軟件需求規(guī)格說明是閱讀和評估代碼的基準(zhǔn).
154.可以將系統(tǒng)的設(shè)計規(guī)格說明作為認(rèn)知代碼結(jié)構(gòu)的路線圖,?閱讀具體代碼的指引.
155.測試規(guī)格說明文檔為我們提供可以用來對代碼進(jìn)行預(yù)演的數(shù)據(jù).
156.在接觸一個未知系統(tǒng)時,?功能性的描述和用戶指南可以提供重要的背景信息,從而更
好地理解閱讀的代碼所處的上下文.
157.從用戶參考手冊中,?我們可以快速地獲取,?應(yīng)用程序在外觀與邏輯上的背景知識,?
從管理員手冊中可以得知代碼的接口|文件格式和錯誤消
息的詳細(xì)信息.
158.利用文檔可以快捷地獲取系統(tǒng)的概況,?了解提供特定特性的代碼.
159.文檔經(jīng)常能夠反映和提示出系統(tǒng)的底層結(jié)構(gòu).
160.文檔有助于理解復(fù)雜的算法和數(shù)據(jù)結(jié)構(gòu).
161.算法的文字描述能夠使不透明(晦澀,?難以理解)的代碼變得可以理解.
162.文檔常常能夠闡明源代碼中標(biāo)識符的含義.
163.文檔能夠提供非功能性需求背后的理論基礎(chǔ).
164.文檔還會說明內(nèi)部編程接口.
165.由于文檔很少像實際的程序代碼那樣進(jìn)行測試,?并受人關(guān)注,?所以它常常可能存在
錯誤|不完整或過時.
166.文檔也提供測試用例,?以及實際應(yīng)用的例子.
167.文檔常常還會包括已知的實現(xiàn)問題或bug.
168.環(huán)境中已知的缺點一般都會記錄在源代碼中.
169.文檔的變更能夠標(biāo)出那些故障點.
170.對同一段源代碼重復(fù)或互相沖突的更改,?常常表示存在根本性的設(shè)計缺陷,?從而使
得維護(hù)人員需要用一系列的修補程序來修復(fù).
171.相似的修復(fù)應(yīng)用到源代碼的不同部分,?常常表示一種易犯的錯誤或疏忽,?它們同樣
可能會在其他地方存在.
172.文檔常常會提供不恰當(dāng)?shù)男畔??誤導(dǎo)我們對源代碼的理解.
173.要警惕那些未歸檔的特性:?將每個實例歸類為合理|疏忽或有害,?相應(yīng)地決定是否應(yīng)
該修復(fù)代碼或文檔.
174.有時,?文檔在描述系統(tǒng)時,?并非按照已完成的實現(xiàn),?而是系統(tǒng)應(yīng)該的樣子或?qū)淼?br />實現(xiàn).
175.在源代碼文檔中,?單詞gork的意思一般是指”理解”.
176.如果未知的或特殊用法的單詞阻礙了對代碼的理解,?可以試著在文檔的術(shù)語表(如果
存在的話)|New?Hacker’s?Dictionary[Ray96]|或在
Web搜索引擎中查找它們.
177.總是要以批判的態(tài)度來看待文檔,?注意非傳統(tǒng)的來源,?比如注釋|標(biāo)準(zhǔn)|出版物|測試
用例|郵件列表|新聞組|修訂日志|問題跟蹤數(shù)據(jù)庫|營
銷材料|源代碼本身.
178.總是要以批判的態(tài)度來看待文檔;?由于文檔永遠(yuǎn)不會執(zhí)行,?對文檔的測試和正式復(fù)
查也很少達(dá)到對代碼的同樣水平,?所以文檔常常會誤導(dǎo)
讀者,?或者完全錯誤.
179.對于那些有缺陷的代碼,?我們可以從中推斷出它的真實意圖.
180.在閱讀大型系統(tǒng)的文檔時,?首先要熟悉文檔的總體結(jié)構(gòu)和約定.
181.在對付體積龐大的文檔時,?可以使用工具,?或?qū)⑽谋据敵龅礁咂焚|(zhì)輸出設(shè)備上,?比
如激光打印機,?來提高閱讀的效率.