寫文件不如錄段影片 - guidde 瀏覽器擴充
寫系統教學文件最大的敵人是每個人都有不同的理解力，有時候你認為自己表達得很清楚了，卻還是有隊友不懂你寫的文件⋯⋯。 這時候與其修改文字段落，不
Posted on Jun 25, 2023 by Amo Chen ‐ 1 min read
documentation
隨手養成 Python 好習慣－勤註解、善用自動文件產生工具 Sphinx
不管是何種程式語言都有註解的需求，而好的程式開發人員都必須具備勤寫註解的美德。
寫註解不僅是為了幫助自己了解程式的相關細節，也是為了能夠讓他人方便於一起參與開發、維護的重要步驟。
正因為現今的系統架構越來越繁雜，而開發人員的大腦記憶能力有限，當他們持續在開發新功能的同時，其實就已經在慢慢淡忘舊功能的實作細節。
特別是每當發現舊功能需要進行維護與除錯時，往往已經過一段時日，開發人員所存的印象早就所剩無幾，更遑論能夠迅速達成維護與除錯的目標。這些現象在程式開發過程屢見不鮮，因此養成撰寫註解的習慣格外重要。
而每個組織對於註解的規定有所不同，但若是對於初學 Python 程式的新進入者而言，可以參考 Google Python Style Guide 對於註解的規範的章節(連結)。
此外，除了註解，通常文件(documentation)也是必備的產出之一，這些細節都可在 GitHub 上的知名專案可見一斑(如 Django , D3 等)。 但基於 DRY(Don’t Repeat Yourself) 原則，我們希望可以在撰寫註解的同時，也一併完成文件的撰寫(相信有許多程式設計師厭惡撰寫文件)，因此本文將介紹如何利用 Sphinx 將 Python 中的註解自動萃取出來，並且自動地產生一份文件供人參考。
Last updated on Jan 11, 2021 in Python 模組/套件推薦 , Python 程式設計 - 高階 by Amo Chen ‐ 4 min read