※ 引述《Starfish.bbs@bbs.hkday.net (海星)》之銘言：
: ※ 引述《VictorHsieh.bbs@ptt.cc (風起鷹揚)》之銘言：
: : 我之前曾在 source code 裡面，用 javadoc 那種方式來寫註解 (硬寫的 XD 見
: : docs/proto/) 當時的想法是，我幫我看懂的 code 註解一下，之後的人就不必重
: : 新去理解 (當然太 detail 或是已經很 trivial 的東西就不必了)。不過後來好像
: : 只有我在寫，我也一段時間沒碰了，所以沒新東西 :p
: : (我這裡指的文件都是指開發人員需要看的部分。)
: 我覺得開發上所需要的document，並不是註解或者像javadoc那
: 些東西可以解決的。除了一些本身比較古怪的code，ptt的程式並不
: 算難看懂了。
我覺得問題在於，我可能想改某個 component 中的一個地方，在沒有文件的
情況下，我可能得把整個子系統看懂。所以有人看懂的子系統，很多都有文
件 (也許不夠完整?) 。另外有些 function 可能有副作用，或是名字沒取好
之類的問題。當時是因為這些原因，才想加上這類的註解。結果後來覺得有
的加有的不加不太統一，就加了不少 ^^;
: 真正需要的是一個跨程序跨模組的說明文件。舉個例，水球系統
: ，在哪個程序觸發啟動，哪個程序編輯訊息，哪個程序收信息，水球
: 資料放在哪裡，以怎樣的格式，整個流程是怎樣？其實不少功能都分
: 佈在不同檔案不同函數裡，而且運作方式也不容易理解，跟蹤程式流
: 程和理解其運作方法就花了大部份時間，真正動手修改相較之下反而
: 十分簡單。所以我覺得獨立的說明文件對開發最有幫助，程式裡的註
: 解次之。
這倒是，有些檔名跟演化到現在的功能多少有些出入了。還有 bbs.c 裡面東西
真的很亂... 還有 include/pttstruct.h ...!@#!@#!@# 但是整個系統有的沒
的功能太多了，想寫這種文件可能得花點工夫分類、整理一下。
有人想寫點東西嗎? :)
--
May the source be with you.
--
※ 發信站: 批踢踢實業坊(ptt.cc)
◆ From: 140.112.244.208