【閒聊】若程式碼已做到 Self-Documenting,還需要寫文件嗎?
7 |
昨天讀了 David 老師的文章:敏捷開發中文件撰寫的必要性?,其中提到,敏捷開發主張「可用的軟體重於詳盡的文件」,User Story 的相關需求文件屬用完可拋,若程式碼己落實 Self-Documenting,那還需要寫文件嗎?
開發系統需要留下哪些文件,該詳細什麼程度,我心中也沒個準。但說程式設計人員不愛寫文件,寧可把時間拿來寫 Code,應該很少有異議。
引述 David 老師的說法:「而程式碼寫得愈好的,就愈不喜歡寫文件,沒有例外。」(為了面子,「我痛恨寫文件」...)
嚴格來說,我並不真的討厭寫文件,而是痛恨「被要求寫文件」,我會主動寫註解、寫備忘錄、寫 Email、寫 FAQ、寫 KB,保留及分享系統的點點滴滴,讓資訊流通透明。但我厭惡「為符合 XXX 規範,請提供文件 A、B、C、D...」,硬擠一堆行禮如儀但沒開發者想看的「文件」(狹義文件論),寧可把同樣時間拿來寫格式不拘,能提供相關資訊的文字 (廣義文件論,更有用且易實踐),給未來的自己、給團隊黟伴、給下一位擦屁股接手維護的新同學。
講到這裡,我也來分享一些個人經驗與想法,聊聊有哪些程式碼 Self-Documentating 也難以補足的有用資訊:
- 規格或需求的上下文 (Context)
程式裡一些不科學不文明做法,有時源自奇葩的客戶要求、逆天的整合架構或不仁道的時程要求,不儘然都是開發者欠缺道德操守或頭被門夾到;有時只看程式碼你很難感受原作者當下的天人交戰與內心掙扎,只覺得「是會不會寫程式呀?花惹發」,但想重構又不敢輕舉妄動。此時若有註解或相關文件交代典故由來、細說來龍去脈,情勢就會改觀。
一則接手的人會對原 PO 多點同理心少點咒罵,降低耳朵癢跟扎草人機率;二則,若有幸遇上有心(而且帶種)重構的熱血青年,這些參考資訊有利於重新審視時空背景變化,估評改善的可能,為系統向上提升帶來龧光。
簡單資訊或許可以直接寫成註解,但依實務經驗,我們往往需要往來信件等級的細節,才足以解釋程式為什為變成這副德行,以及現在能不能改。如不想花太多時間整理文件,光妥善保存往來討論信件都很有幫助。 - 系統概述 (Overview)
雖說你永遠可以從程式碼推敲還原整個系統架構與運作邏輯,但什麼史料都不交接,代表每個接手的人得重新從底層摸索一次。(過來人學長說:「一袋米要扛幾樓,拎杯也是這樣苦過來的,幹!」) 我習慣摸索古蹟系統的程式脈絡時,用積德行善心情順手整理出架構圖、資料流程之類的概述或概念性文件,希望讓後人少走點冤枉路,能更快上手好把維護工作甩給他。接手系統時若驚喜拿到前人留下的相似文件,我也會讚嘆感恩連連,把它當成「善的循環」,哈! (但很不幸機率不高,也算印證開發者不愛寫文件的習性) - KB、FAQ、SOP
這類文件零散歸零散,但格外好用,能大幅降低後人撞牆機率及降減少問題處理時間。它們很接近系統維護文件,但形式上更瑣碎且格式多變,有時需依賴可分類及搜尋的系統集中管理。實務上倒也不需要多豪華的知識管理系統,用公司資料夾、公用信箱、Wiki,甚至發個 Email 採去中心化方式存進大家的信箱都好,有被寫下來比較重要。 - 稽查或檢核用文件
即便實質幫助不大,規章辦法總會規定系統需備妥指定規格的系統分析書、資料庫 Schema、系統功能列表、程式檔案清單... 等一干文書。我是覺得,任何一份用心整理,不到 10 頁的系統簡介既維護注意事項(裡面有學長滿滿的愛啊)都勝過這類交差用的數百頁文檔,真派上用場機會有限。不過,既為高裝檢必查項目,吾等仍應備妥敬待檢閱:ChatGPT/Github Copliot,就決定是你了~ (誤)
在做開發的同學們,大家會習慣寫文件嗎?也會寫 Memo/KB/FAQ/SOP 嗎?歡迎分享經驗。
Comments
# by SY
以前的我也是會大吼,這程式是誰寫的!! 直到幾次發現那是我自己寫的之後,我現在能夠將心比心,甚至能從程式中嗅出當年面對使用者畸形要求的情景
# by Allen C.
會寫流程、資料庫 Schema、複雜的判斷條件, 不然會忘記 ...
# by Eric
反直覺的決策都要寫下來不然下次爆炸的時候沒辦法究責。 明明是別人決定的,沒寫下來就要RD背鍋了。
# by 陳阿胖
以前留過一段註解 //我測不出來,但我直覺這段有用 若干年後 //胖說的沒錯這段真的有用 我同事是無用的CODE就清掉的派系
# by wellxion
養成註解和readme.md的撰寫習慣真的很重要 尤其有些神奇邏輯 但有時候留下意義不明的註解 還有沒刪乾淨的 都真的滿困擾人的
# by Johnston
解決過的問題或是用奇怪的 tweak 做的 feature 都會紀錄下來,以供後人了解當初為什麼這樣做,讓他們在更改 codebase 的時候有個基礎了解很重要
# by motovb
David 老師的說法:「而程式碼寫得愈好的,就愈不喜歡寫文件,沒有例外。」 不同意啊!Code 只能解釋 do what,不能解釋 why to do by this way. design 都是 trade-off,沒有寫下當時的 trade-off,常會被質疑為什麼不能用其他種做法。