程式人與開發文件之間的恩怨情仇

撰寫開發文件，恐怕是許多程式人內心深處最不願意碰觸的一個領域。大多數的程式人認定，工作的職責在於程式設計，而對於「撰寫」開發文件，多半避之唯恐不及，甚至認為那是浪費生產力。

文件設計不佳又沒有審閱制度，就形成交差了事
我的第一份程式設計工作，有一個相當特殊的規定：星期一至四寫程式；星期五寫「文件」。在我的這一份工作中，程式人被要求撰寫的文件，是程式碼作用的說明文件。

公司會有這樣的要求，根本的原因還是在程式碼的銜接。在這公司中，每個程式人都只照料自己撰寫的程式碼，而各自所照料的程式碼，也就只有自己最熟悉，倘若遇上離職或工作需要交接，難免製造出額外的負擔和困擾。在遭遇幾次此類的風波後，公司決定實施4天撰寫程式碼，1天撰寫說明文件的制度。

對程式人來說，程式碼完成了，幾乎就認定工作完成了。遇上必須撰寫程式碼說明文件的硬性規定，無不視為工作以外的額外負擔。可以想見：倘若沒有徹底地實施審閱制度，那麼文件多半只是徒具形式。

沒有適當的審閱制度、沒有統一的文件結構，那麼文件本身是不是正確、能否充份表達程式碼的作用，或者易於理解，都會構成極大的問題。這正是許多文件在開發流程中的問題，文件有本身打算達成的目標，可是文件的設計及配套措施，並不足以輔助文件達成目標，最後便使得文件形式化，所有人也就以一種應付、交差了事的態度面對。

若不能帶來助益，文件勢必被視為負擔
上例的程式碼說明文件，只是軟體開發會涉及的文件的一類。事實上，程式人可能涉及的文件，隨採用的開發方法或流程規範的不同，還會有各種類型。例如，負責系統設計的程式人，就必須撰寫設計文件。

但不論是那一類型的文件，僅具形式、過度工程化（過度擴張需求），都會造成程式人對文件持有負面觀感。

此外，程式人之所以視開發文件為洪水猛獸，有一個很主要的原因是：這些文件的存在是基於管理甚至是業務的需求。

我看過許多專案在即將交付客戶之際，才開始撰寫系統分析、系統設計的文件，原因無他，只是因為這些文件是合約中明訂必須交付的項目。而當這些文件的撰寫是基於此類的目的時，更容易被程式人視為額外的負擔。

不論是流程文件（例如像輔助建構管理流程的「簽出簽入登錄表」）或開發技術文件（例如系統設計文件），若不能為開發工作帶來真正的助益，便代表文件有根本的問題。而這麼一來，更難說服程式人打從心裡接受它。

不論你所採用的開發方法論為何，基本上在整個開發工作中總難免涵蓋系統分析、設計、實作，以及測試等工作。只不過，在不同的開發方法下如何執行、串接，以及各項工作的份量不盡相同罷了。
對於大型的團隊來說，系統分析人員、系統設計人員、程式實作人員、測試人員等角色，往往各司其職。

對程式人來說，多半專職於程式撰寫的工作，或是客串一下系統設計人員。諸如系統分析文件，那是系統分析人員的份內工作，沒有程式實作人員會抱怨這些文件帶來額外負擔。

不過，對於小型、輕量級的開發團隊來說，一名程式人或許同時扮演系統分析、系統設計、以及程式實作的角色，過於繁文褥節的系統分析文件，就帶來很大的產能損失及怨言。

從建模的觀點，文件的作用是輔助產出程式碼
若是系統都已經完成了，才開始補文件，自然會讓開發人員認為文件是多餘的，因為沒有這些文件，系統也能完成，自然而然會造成開發人員對撰寫文件的抗拒心理。

事實上，開發中所產出的文件，是為了輔助系統的建構而生的。我很喜歡有些人利用「建模（Modeling）」來描述他們所做的系統分析，以及系統設計工作。

系統分析及系統設計是系統實作的前期工作，效用在於為即將實作的系統，提供一個具體而微的模型。人們喜歡用建造建築物比喻建構軟體的過程。而在現實生活中，人們在利用鋼筋、水泥等材料建造一棟大樓之前，總是會先繪製設計圖、建立大樓模型。

在我們還沒有完全明白所要打造的東西，得透過一個漸進的過程，逐漸拓展對它的認識。所以，我們先做系統分析，了解目標為何。

接著，做了高階設計，描繪出系統高階的抽象樣貌。再來，進行低階設計，更深入的探索將逐漸靠近實作層次的細節。總算，我們有了一整套的施工藍圖，得以按圖中的描繪，啟動具體的建造工作。

從「建模」的觀點來看，系統分析文件及系統設計文件，是我們在開始撰寫實際的程式碼時的中間產物，它們是越來越清晰、越來越具體的模型。作用在於輔助產出最後實際的程式碼，而不是僅有形式的象徵。

許多程式人對於文件的反感，來自於組織看待文件的角度失焦。由於未適度的因應團隊及產品的特性，調整文件需具備的元素，使得組織所規範設計的文件格式，內含過多的元素，不能為接下來產出程式碼派上用場。

也就是說，組織不知道應當權衡折衝，針對團隊的特性，留下真正有用、同時捨棄可能過度浪費生產力的元素。

你是在建立模型，而不是在「撰寫文件」
以組織的角度來看，應當要設計適宜的流程及文件，在不造成過度負擔的情況下，兼顧文件做為溝通、記錄、建模等的用途。這些文件應是輔助整體開發的中間產物。

而從程式人的角度來看，開發中所產出的文件，不應是程式碼撰寫之外的額外工作。它們是輔助你寫下具體程式碼的縮小抽象模型。或許表面上可以不做任何分析、設計的工作，但實際上也不過只是把分析和設計的工作，濃縮在寫程式的階段一起進行而已。

程式人還是得在撰寫程式碼的同時考量、分析系統應有的長相，得在腦中描繪系統的高階架構。但更糟的是，把事情混在一塊做，就沒有辦法漸進式地在不同的抽象層級上，以適當的抽象程度來思考系統。

當你需要和多人一同工作時，沒有一個擺在大家面前可供討論、溝通的模型，又要如何確保彼此之間的認知是一致的呢？這中介的模型，應當是用來協助程式人寫下最終程式碼的輔助工具，而不是浪費生產力的凶手。

這正是許多程式人對此類文件最大的誤解所在。事實上，你不是在「撰寫文件」，你是在建立系統的模型。

因此，應讓團隊在專案的不同階段，適度的完成該階段應該達成的目標，並且產出文件。許多團隊往往不在系統分析階段做分析，不在系統設計階段做設計，他們拿著混凝土就直接灌起漿來了。而文件當然可以後補，運氣好的話，憑藉著團隊中幾位天才洋溢的程式人，大樓還能維持一定品質。但若先天不良，後天再失調的話，這大樓恐怕就會搖搖欲墜。

作者簡介：
王建興
清華大學資訊工程系的博士研究生，研究興趣包括電腦網路、點對點網路、分散式網路管理、以及行動式代理人，專長則是Internet應用系統的開發。曾參與過的開發專案性質十分廣泛而且不同，從ERP、PC Game到P2P網路電話都在他的涉獵範圍之內。