首頁 / 文章導讀 / THE MYTHICAL MAN-MONTH / The Introduction of The other face

The Introduction of The other face

這是人月神話:軟體專案管理之道(20週年紀念版)的第十五章:(),簡體版譯作另外一面,到是很直覺,而一體兩面四個字用起來很像是成語,不過譯的是否貼切,有待進一步觀察。ㄚ琪從頭到尾看完一遍,很抱歉看不出內容跟主題關聯的情形,倒是開場白歌德『What we do not understand we do not possess.』『我們無法主宰我們不瞭解的東西』,倒是滿貼切的,這一篇對ㄚ琪來說,是個很實用的建議,我應該會把裡面的教學做在我的程式裡頭。本篇的重點就是「如何」寫好文件。

該寫哪些文件?

為使用程式而寫的文件 這裡主要針對文件應該先有概觀性的描述(overview),作法引用簡體版並譯成繁體字使用如下:

1. 目的。主要的功能是什麼?開發程式的原因是什麼?

2. 環境。程式運行在什麼樣的機器、硬體配置和作業系統上?

3. 範圍。輸入的有效範圍是什麼?允許顯示的合法範圍是什麼?

4. 實現功能和使用的演算法。精確地闡述它做了什麼。

5. 輸入-輸出格式。必須是確切和完整的。

6. 操作指令。包括控制臺及輸出內容中正常和異常結束的行為。

7. 選項。用戶的功能選項有哪些?如何在選項之間進行挑選?

8. 運行時間。在指定的配置下,解決特定規模問題所需要的時間?

9. 精度和校驗。期望結果的精確程度?如何進行精度的檢測?

這樣就可以寫出3到4頁的摘要性說明,這裡頭有些ㄚ琪還需要改善自己的文件說明,但是環境常常會省略掉,以後應該會加入進來。

為建立對程式的信心而寫的文件 這句話的意思就是增加測試案例(test case),我倒是沒有寫這個文件的習慣,改吧。這種文件有三部份:主案例、罕見合法案例及罕見不合法案例。

為修改程式而寫的文件 包含的部份:

1. 流程圖或副程式的結構圖,對此以下有更詳細的論述。

2. 對所用演算法的完整描述,或者是對文件中類似描述的引用。

3. 對所用檔案規劃的解釋。

4. 解譯階段結構(pass structure)的概觀——從磁片或者磁帶中,獲取資料或程式處理的序列——以及在每個處理過程必須完成的操作。

5. 初始設計中,對已預見修改的討論;特性、可插入點(hooks)與離開點(exits);原作者對可能會擴充的地方以及可能處理方案的一些意見。另外,對隱藏缺陷的觀察也同樣很有價值。

惱人的流程圖

這個流程圖到是很讓ㄚ琪頭痛,因為ㄚ琪從來沒有將流程圖做出來過,但是在看別人寫的程式時,卻又很希望作者有流程圖可以讓人參考,很矛盾吧,好在作者也不建議做流程圖,終於有跟ㄚ琪同一陣線的人了,給個讚,但是作者反倒建議將程式轉成以執行階段或步驟為主的結構圖,然後畫在一頁大小的流程圖上,倒是滿方便的,舉例如下圖:

2011-05-03_163713

這裡還引用使徒行傳15:10『現在為什麼試探神,要把我們祖宗和我們所不能負的軛放在門徒的頸項上呢?』,當然典故ㄚ琪就不多說了,只能說作者用聖經的話來強烈支持不做流程圖,ㄚ琪頗認同這觀點。

自我說明程式

這裡頭建議把書面說明寫到程式碼裡,這樣可以大幅改善維護工作,而且保證程式使用者可以隨時便利地參考文件,這種作法稱為程式的自我說明(),感覺好像Java的說明文件喔,很有可能是有這裡衍生出來的。

可行的方案

第一個想法是借助那些出於語言的要求而必須存在的語句,來附加盡可能多的“文件”資訊。因此,標籤、宣告、符號名稱均可以作為工具,用來向讀者表達盡可能多的意思。

第二個方法是盡可能地使用空格和一致的格式提高程式的可讀性,表現從屬和巢狀關係。

第三,以段落注釋的形式,向程式中插入必要的敍述性文字。

拒絕去做的理由 我想已經沒有理由了吧,Java都弄的嚇嚇叫了,甚至組合語言也可以這樣做吧,那就很cool了,不過這樣的文件如果有時來個範例說明,感覺就更好用了,當然這是以在學者的角度來看的。

Print Friendly, PDF & Email
馬上成為工作達人的Fans

About ㄚ琪

工作達人Fun Taiwan的創辦者及總編,可以在這裡更認識他。

發表迴響

你的電子郵件位址並不會被公開。 Required fields are marked *

*

這個網站採用 Akismet 服務減少垃圾留言。進一步瞭解 Akismet 如何處理網站訪客的留言資料

Scroll To Top