只有 SRC 沒有 DOC

只有 SRC 沒有 DOC - Protocol

by thinker

關鍵字:

使用 open source 程式碼時，經常只有 source code ，而沒有 design document 。如果程式寫的不好，變數、函數名稱亂取，那就更加麻煩。了解這樣的系統，豈止「頭痛」了得。

要分析這樣的程式碼，如我在 linkname:[模組的關聯度] http://heaven.branda.to/~thinker/GinGin_CGI.py/show_id_doc/245 所言，必需先了解模組的切割和關聯。要了解模組的切割，必需先了解其 interface 。 Interface 主要是由 data structure 和 exported function 所組成。了解 interface ，就必需先了解這些 structure 和 function 的作用。於是乎，一切從了解 structure 的作用開始。

了解 structure 和 function 的作用，除了從內部了解，除外部觀察也很重要。大部份人 (就是鄙人) ，可能很快的鑽進 function 的程式碼裡，試圖透過了解程式的流程，進而了解 function 的作用和 structure 的角色。這樣作法，往往使自己落入隱晦而未知的資訊陷阱裡。這個資訊陷阱來自於程式碼本身的資訊不完善，許多隱性資訊在，在 $coding$ function 時，未被完整表達。一旦掉入這類陷阱裡，往往想破頭也無法了解。

然而，這些資訊如果未被寫進程式碼裡，程式又如何能運作。事實上，只是資訊被分散了，被分散到使用這些 function 的程式碼裡。這部分資訊，我稱之為 protocol 。 Interface 的使用規則，包括使用順序、相依性、和外部狀態，總合而成為 interface 的 protocol 。 Interface 的使用者，必需依循這個 protocol ，以確保 module 正常運作。

protocol 的資訊，往往未被寫在 interface 的 implementation 裡，也就 function 裡。文件和註解，往往也忘了記載，只留在 programmer 的腦袋裡。這時侯，單從 interface 的 implementation 無法得到這些資訊。這些資訊都暗埋在使用案例裡。也就是，我們必需透過了解其它 module 在什麼時機、呼叫哪個 function 、給予什麼資訊，進而建構出 protocol 的全貌。

因此，除了看 implementation 的流程之外，找尋案例也是很重要的步驟。找尋案例，可以透過 grep ，這個簡單好用的工具。 grep 的好處是幾乎隨手可得，至少在 UNIX like 的系統上。然而， grep 的效能不彰，必需花很多時間才能從大量資料中，找到你要的資訊。

我個人推薦使用 linkname:[GNU GLOBAL] http://www.gnu.org/software/global/ ，這個 tag system 。 GLOBAL 事先為程式碼建立 $database$ ，可以查 function 的位置，也可以查呼叫特定 function 的位置。這些都在一瞬間就完成。 trace source code 的人，是無法忍受等待的。一瞬間找到所要的資訊是必需的，否則只會惱怒。

最後更新時間: 2007-06-13 10:55:34 CST | 引用

查詢:

COMMENTS:

on 2007-06-14 01:59:54 CST

av said ..

丟給 VC, 不必 compile, 用 Visual Assist 就好了!

on 2007-06-14 10:24:52 CST

Thinker said ..

習慣在 terminal 工作，一時也沒想到 IDE 環境。 Open Source 的 solution ，可以考慮 source-navigator http://sourcenav.sourceforge.net/ 。