【閒聊】若程式碼已做到 Self-Documenting，還需要寫文件嗎？

昨天讀了 David 老師的文章：敏捷開發中文件撰寫的必要性?，其中提到，敏捷開發主張「可用的軟體重於詳盡的文件」，User Story 的相關需求文件屬用完可拋，若程式碼己落實 Self-Documenting，那還需要寫文件嗎？

開發系統需要留下哪些文件，該詳細什麼程度，我心中也沒個準。但說程式設計人員不愛寫文件，寧可把時間拿來寫 Code，應該很少有異議。

引述 David 老師的說法：「而程式碼寫得愈好的，就愈不喜歡寫文件，沒有例外。」(為了面子，「我痛恨寫文件」...)

嚴格來說，我並不真的討厭寫文件，而是痛恨「被要求寫文件」，我會主動寫註解、寫備忘錄、寫 Email、寫 FAQ、寫 KB，保留及分享系統的點點滴滴，讓資訊流通透明。但我厭惡「為符合 XXX 規範，請提供文件 A、B、C、D...」，硬擠一堆行禮如儀但沒開發者想看的「文件」(狹義文件論)，寧可把同樣時間拿來寫格式不拘，能提供相關資訊的文字 (廣義文件論，更有用且易實踐)，給未來的自己、給團隊黟伴、給下一位擦屁股接手維護的新同學。

講到這裡，我也來分享一些個人經驗與想法，聊聊有哪些程式碼 Self-Documentating 也難以補足的有用資訊：

1. 規格或需求的上下文 (Context)
   程式裡一些不科學不文明做法，有時源自奇葩的客戶要求、逆天的整合架構或不仁道的時程要求，不儘然都是開發者欠缺道德操守或頭被門夾到；有時只看程式碼你很難感受原作者當下的天人交戰與內心掙扎，只覺得「是會不會寫程式呀？花惹發」，但想重構又不敢輕舉妄動。此時若有註解或相關文件交代典故由來、細說來龍去脈，情勢就會改觀。
   一則接手的人會對原 PO 多點同理心少點咒罵，降低耳朵癢跟扎草人機率；二則，若有幸遇上有心(而且帶種)重構的熱血青年，這些參考資訊有利於重新審視時空背景變化，估評改善的可能，為系統向上提升帶來龧光。
   簡單資訊或許可以直接寫成註解，但依實務經驗，我們往往需要往來信件等級的細節，才足以解釋程式為什為變成這副德行，以及現在能不能改。如不想花太多時間整理文件，光妥善保存往來討論信件都很有幫助。
2. 系統概述 (Overview)
   雖說你永遠可以從程式碼推敲還原整個系統架構與運作邏輯，但什麼史料都不交接，代表每個接手的人得重新從底層摸索一次。(過來人學長說：「一袋米要扛幾樓，拎杯也是這樣苦過來的，幹!」) 我習慣摸索古蹟系統的程式脈絡時，用積德行善心情順手整理出架構圖、資料流程之類的概述或概念性文件，希望讓後人少走點冤枉路，能更快上手好把維護工作甩給他。接手系統時若驚喜拿到前人留下的相似文件，我也會讚嘆感恩連連，把它當成「善的循環」，哈! (但很不幸機率不高，也算印證開發者不愛寫文件的習性)
3. KB、FAQ、SOP
   這類文件零散歸零散，但格外好用，能大幅降低後人撞牆機率及降減少問題處理時間。它們很接近系統維護文件，但形式上更瑣碎且格式多變，有時需依賴可分類及搜尋的系統集中管理。實務上倒也不需要多豪華的知識管理系統，用公司資料夾、公用信箱、Wiki，甚至發個 Email 採去中心化方式存進大家的信箱都好，有被寫下來比較重要。
4. 稽查或檢核用文件
   即便實質幫助不大，規章辦法總會規定系統需備妥指定規格的系統分析書、資料庫 Schema、系統功能列表、程式檔案清單... 等一干文書。我是覺得，任何一份用心整理，不到 10 頁的系統簡介既維護注意事項(裡面有學長滿滿的愛啊)都勝過這類交差用的數百頁文檔，真派上用場機會有限。不過，既為高裝檢必查項目，吾等仍應備妥敬待檢閱：ChatGPT/Github Copliot，就決定是你了~ (誤)

在做開發的同學們，大家會習慣寫文件嗎？也會寫 Memo/KB/FAQ/SOP 嗎？歡迎分享經驗。