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

[darkkiwi (....)]

   最近小弟的工作是在幫部門寫一些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
推 easy1:所以...你是寫 別人設計的interfac 的文件? 還是自己的?
推 leicheong:function的說明有一個原則, 就是假設10年後你再維護這段
→ leicheong:程式的時候, 能單靠看這段說明就可以另外寫出功能/效果
→ leicheong:相同的東西, 這就合格了. :)
→ leicheong:做不到的話, 要不是寫得太差的話, 就是這function弄得太
→ leicheong:複雜. 建議再refactor一下...