[討論] 關於軟體文件的撰寫

看板CSSE (電腦科學及軟體工程)作者darkkiwi (....)時間16年前 (2008/11/29 13:28)推噓2(2推 0噓 4→)

留言6則, 2人參與討論串1/1

最近小弟的工作是在幫部門寫一些interface functing的文件，為的是某些module要交給其他部分使用，我被要求寫一些類似MSDN的文件，描敘function的功能、傳入參數、回傳值，這看似相當普遍的工作，但當我真的開始著手進行時，發現了一些困難點，讓我覺得文件這種東西是，食之無味、棄之可惜，甚至是拿來做樣子當擋箭牌。因為module的行為往往十分複雜，搞得interface也很窒礙難懂，面對面溝通再加上畫圖都講不清楚，更何況是用文字? 還是Chinese English? 複雜的還不只function本身，連代入的參數也可能高達七八個，甚至還有一些是自訂的structure，裡面包什麼還得另外看，代入的東西還有reference value，去取值用的，以及callback function，這簡直一發不可收拾.... 我在公司部門裡算資淺的，面對這些問題的時候雖然會存疑，但也不敢表示什麼，寫這些interface的同事也許是自己已經很熟悉，總是認為已經很簡單很方便了，有時真的搞不清是自己理解能力太差，還是這些interface真的太複雜? "了解別人在做什麼" 這句話講起來真的是正氣凜然無法反駁，但我一直認為module最好做到跟外界絕緣，interface要簡單到近乎愚蠢，以一個使用者的角度來看，我根本懶得去知道這module裡頭怎麼實作，我只想知道它可以做什麼，而且最好你可以教會我，別讓我還得自己去看code。不過我不敢跟其他人這樣說...科科~ 我不知道這算不算軟工的範圍，也覺得這問題感覺上小不拉機似乎拿不上抬面，但小弟資質愚魯，怎麼想都想不透怎樣的作法才是對的? 望有想法的前輩可以不吝指教，拜謝。 -- 為什麼那邊那個人那麼傷心呢? ││││││ 因為他是台灣人啊，吃的比我們還毒哩! 2.5ppm ˍ︵ │││ 還好我們 0.5ppm ꈠꈠ2ppm ╱ ╱▏ ││ 不用吃… ꈠ ꈠ ◤ ◥ │￣▏ ˍ 0ppm | | | ╱ ╱ ꈠ 兞1m◢ ꄠ （||） ω ꈠㄦ -- ※ 發信站: 批踢踢實業坊(ptt.cc) ◆ From: 221.169.231.18 ※ darkkiwi:轉錄至看板 Tech_Job 11/29 13:38