推 ggg12345:很值得參考的做法. 04/06 01:39
※ 引述《NDark (溺於黑暗)》之銘言：
: ※ 引述《ggg12345 (ggg)》之銘言：
: 1. 工程人都不喜歡寫文件。這是真的，喜歡寫文件能寫文件的可能就不會走這條路。
: 3. 文件寫到夠用，看得懂就好。使用一些共同編輯的工具減少文件的維護問題（譬如說
: 註解或wiki）。
恕刪其它
分享一下我自己的經驗
首先，先搞清楚文件要到什麼樣的等級
如果你是寫Library來賣的或是開發Library，請參考一下Java Doc或MSDN
這一類的文件是給千萬人讀的，當然就應該答到更高的水準/要求
再考慮什麼樣的文件是合理的情況之前，請先考慮好你的讀者
舉個例來說，如果我自己的研究，自己的軟體，自己看，也不打算和別人合作
從一開始就只是為了我自己，所以寫註解是為了什麼未來方便看
相信我，遲早你會需要的DEBUG自己的CODE
在這種情況，所的文件當然和前面講的Library不可同日而語
想要硬推 文件>COMMET>CODE 是在找自己麻煩
一天就是八小時，花愈多時間寫文件，就愈少時間寫CODE/測CODE
寫文件不如去寫UNIT TEST比較實在
很多人連TEST都不寫，就在那談寫文件那很奇怪
好了，一般的情況，程式是寫給
(1)未來接手的人看的 <-- 我那知道你水準到那
(2)同組的其它人 <-- 有問題不會來問嗎
(3)自己
私以為1跟2看情況，但3絕對不能自己騙自己
以公司的角度，這樣是很自私，也很不利的
所以小型公司(或是START UP)或是小案子，我通常採用這下面的方式
把程式設計師二二一組，實力請相當，最好互為代理人(動機才強)
一個人寫完CODE後加COMMENT請另外一個人讀，讀的時候確保能了解
(有時候寫文件的人會有盲點…)
確定沒問題之後送給主管或是資深的LEAD快速REVIEW
好的CODE應該要能直接讀懂(至少對同組或你的代理人)
CHECK IN之後，確定不再大改了，把CODE整理乾淨
沒有用到的COMMENT或是HISTORY拿掉
寫一份簡單文件(通常寫在CODE最前面用/** */ + RestructedTExt寫)即可
說明該程式的用途及內容
至於如何執行，請寫Scenario Test，然後把這些TEST寫到WIKI去
當然歡迎多寫，但這就是基本
新人加入就丟個老鳥帶，基本上一開始就是讀別人的CODE
通常(不是整新人)，我都會要他讀懂後 "講" 給我聽一遍
每個案子結案前請各個模組的人才開始寫高階設計書(交差用)
當然，這個高階設計書其實就是從PM或是一開始討論的草稿/PPT
把他們好好整理，文字補齊，弄漂亮一點
有人離職前，主管和他一起GO 一次他主要負責的程式
大概小案子(十人以下)就用這樣的方式
當然，也有可能最近我寫PYTHON寫得很多，所以對文件的要求似乎比較低
為什麼我不鼓勵 文件時間>寫CODE時間
可能是因為我參與的東西，基本上SPEC天天在改
有新的想法可以舊的整個丟了或砍掉重練
或是講直接一點，本來就一直在PIVOT…
除了核心(大家都會CALL)的部份，大部份的CODE都用上面的方式搞定
原則上，大概抓20%文件 + 30%寫測試 + 40%CODE + 10%寫WIKI
當然，上面講的都是"小型""不斷改變"的Project
不是那種寫好後，十年不打算動(或重寫)的銀行系統一類的…XD
--
※ 發信站: 批踢踢實業坊(ptt.cc)
◆ From: 131.179.64.159
※ 編輯: chucheng 來自: 131.179.64.159 (04/06 00:45)