4 posts
Literate programming 將 Markdown 檔案作為單一事實來源，使文件、測試和實作保持同步。以下是如何用三十行 Python 實現它。
你的文件、測試和程式碼是三份檔案，講著同一個故事，卻講得都很糟糕。 你在原始碼裡更新了函式簽名，忘了改 README 裡的範例。一週後，新進員工把過時的程式碼片段複製到了生產環境。你的測試檔案仍然把舊的行為編碼為預期結果。現在你有兩個 bug 和一個文件工單。…
LLM 對話包含意圖、被拒絕的替代方案以及可執行的程式碼。這正是文件應該包含的內容。以下是將 ephemeral chat 轉換為持久、可搜尋的文件，同時不遺失敘事的方法。
你花了 45 分鐘和 Claude 設計一個 retry circuit。你解釋了 failure modes，因為 exponential backoff 會掩蓋 cascading pressure 而拒絕了它，確定了 token-bucket rate limiting with…
Literate programming承諾程式碼應該首先為人類編寫，其次才是為機器。四十年後，幾乎沒有人這樣寫。以下是軟體文件化中最優雅的理念為何未能改變我們工作方式的原因。
1984年，Donald Knuth發表了一篇提出根本性反轉的論文。程式不應該是為編譯器編寫、為人類添加註解的。它們應該被寫作為人類的文學作品，編譯器從中提取可執行部分。他稱之為literate programming，並以此方式建構了TeX。 這個想法很美。它在現代軟體開發中也幾乎完全缺席。…
架構文件從你存檔的那一刻起就開始腐敗。以下說明如何透過程式碼產生的圖表、ADR 與自動化架構測試，讓文件保持誠實。
我在 wiki 裡看過的每一張架構圖都是錯的。不是明顯的錯，而是安靜地、漸進地錯。標示為「Auth」的服務在六個月前就被拆成三個微服務。標示為「sync call」的箭頭現在已經透過 queue 變成 async。標示為「PostgreSQL」的資料庫在某次火災演練中被遷移到別的東西，但沒人更新那個方框。…