iT邦幫忙

DAY 20
5

程式設計心法系列 第 20

程式設計心法:19.說明文件

  • 分享至 

  • xImage
  •  

寫程式最討厭的一件事情是什麼?我想大家一定會舉雙手贊成--文件!
文件很多時候不是給程式設計師看的,所以就不能以程式設計師的語言去寫。
這就是傷腦筋的地方!

如果是 API 文件,那麼有很多工具可以使用,如 JavaDoc

量身訂做自己的 JavaDoc 上
量身訂做自己的 JavaDoc 下

配合註解的定義與規範,就可以產生一份極具參考價值的 API 文件。

Visual Source Safe 也可以透過註解中一些特殊的設定,也可以做成一份很有用的說明文件(Sorry 如何製作的文件已經找不到了,現在 .Net 環境則改以 Team Fundation Server 來取代 Visual Source Safe 了)
其實系統設計文件,上述的 API 文件製作,或者將每一個單元開發以 Blog 的方式撰寫,都是蠻好的一種方式。

最常在專案中看到的是使用手冊與操作手冊。這兩者有和區別?使用手冊是給使用系統的使用者看的,操作手冊則是給資訊人員看的。這部份在軟體技術文件指引手冊中,有很詳細的撰寫說明,可以去下載來參考。
http://210.71.186.144/cgi-bin/big5/cisa/aa02

以我們公司使用的 ERP 系統(鼎新 Tiptop),我想很多人對他詬病很多(大多數不是對系統本身,因為大部分都跟原始系統差很大了,而是對該公司的服務...XD),但是就系統文件的角度來說,他可是蠻有規劃的(但命名方式就很可議)。

首先,路徑的定義明確,每一個系統模組對應一個程式路徑,每一個路徑底下都分為程式、畫面、Schema、help等目錄,他的畫面與 Schema 就頗具參考價值。程式開發完成的同時,相關的文件也就因應產生。雖然我不是負責 ERP 的開發,但是開發一些外部程式,少了這些文件就完全無法運作。更重要的是,他有固定的命名方式與規則。熟悉了自然就能掌握。

當然,這是屬於 Informix 4GL 的特性,但是如果我們開發程式能夠參考以上的作法,事實上,真能幫我們做好文件,提供很有用的資訊。

本系列文章


上一篇
程式設計心法:18.註解行不行
下一篇
程式設計心法:20.除錯(Debug)
系列文
程式設計心法31
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中
0
海綿寶寶
iT邦大神 1 級 ‧ 2009-10-26 09:23:10

我個人是崇尚「自動化產生文件」那一派的
所以只要我看到用Word做的漂漂亮亮的
系統文件或是測試報告
我都會覺得文件很不實在,甚至是假的,
但偏偏就是有人喜愛這一套

就連最基本的Database schema
也有更誇張的說法
「文件寫好的同時,就是文件失效的時間」
(因為schema又改了,而文件卻沒跟著改)

0
fillano
iT邦超人 1 級 ‧ 2009-10-26 10:07:15

這個很無奈...(我就碰過SQA設計出來的文件範本做得...簡單說,有重複使用的困難度)

0
fillano
iT邦超人 1 級 ‧ 2009-10-26 10:16:15

最理想的狀況是:文件有專用的wiki跟wiki範本可以用,有自動化流程,做完單元跟整合測試報表自動上傳,JavaDoc自動做出API文件等等啦。而且透過持續整合來驅動。所有文件都用html格式的話,容易做自動化了。DB Schema有線上工具可以用來做設計,設計結果可以直接更新到DB跟文件,並且有Plugin可以直接生成model的程式...

所有文件都是word,那真是惡夢一場...

看更多先前的回應...收起先前的回應...

沒錯
而我現在天天都活在惡夢中....Orz

jamesjan iT邦高手 1 級 ‧ 2009-10-26 12:24:59 檢舉

沒錯
很多單位要求文件都要美美的,厚厚的
可以擺在桌上裝飾的...XD

echen688 iT邦高手 1 級 ‧ 2009-10-26 12:30:36 檢舉

其實厚厚的文件拿來蓋泡麵碗最好用了....(誤)

我還碰過這種的...

我問了驗收單位一個白癡問題:「文件大概要做到什麼程度才OK?」
驗收單位:「把每一份文件印出來然後裝訂,站著放,如果不會倒就差不多了」

0
jamesjan
iT邦高手 1 級 ‧ 2009-10-26 12:29:47

以前做專案,也沒聽說過 CM(Change Management)這種東西

後來有機會參與財金公司的一個專案(應該說是見習),IBM 主導的
除了 Fly in 的 Consultant,以及眾多的本地系統分析的人員,陣仗之大外,還有一個小姑娘,令人很驚訝的是,所有的人對他都畢恭畢敬的,後來打聽才知道他是負責 CM 的,妳想改什麼,都得透過他同意才可以做文件的修改!...XD

小姑娘
NPNT
零昏

0
Peter
iT邦新手 5 級 ‧ 2019-04-18 16:08:09

該頁面連結均已失效,麻煩jamesjan補上連結謝謝

我要留言

立即登入留言