最近小弟的工作是在幫部門寫一些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