4 posts
Literate programmingは、Markdownファイルをsingle source of truthにすることで、ドキュメント、テスト、実装を同期させ続ける。Python30行で実装する方法を紹介する。
ドキュメント、テスト、コードは、同じことをまともに語れない3つのファイルだ。 ソースの関数シグネチャを更新する。READMEのサンプルを忘れる。1週間後、新入社員が古くなったスニペットを本番にコピーする。テストファイルはまだ古い動作を期待結果としてエンコードしている。これでバグが2つ、ドキュメントチケットが1つだ。…
LLMの対話には意図、却下された代替案、そして動作するコードが含まれています。これこそがドキュメントであるべきものです。以下に、短寿命なチャットをナラティブを失うことなく、永続的で検索可能なドキュメントに変換する方法を説明します。
あなたはClaudeと45分かけてリトライ回路を設計しました。失敗モードを説明し、カスケード圧力を隠してしまうため指数関数的バックオフを却下し、jitter付きtoken-bucket rate limitingで決着し、動作する実装を生成しました。説明は明快で、推論は妥当であり、コードは実際にテストをパスしました。…
Literate programmingは、コードは人間のために先に書かれ、機械のために次に書かれるべきだと約束した。40年後、ほとんど誰もそのように書いていない。なぜソフトウェア文書化における最もエレガントなアイデアが、私たちの働き方を変えられなかったのか。
1984年、Donald Knuthは根本的な転換を提案する論文を発表した。プログラムはコンパイラのために書き、人間のために注釈をつけるべきではない。プログラムは人間のための文学として書かれ、そこからコンパイラが実行可能な部分を抽出すべきだ。彼はこれをliterate…
アーキテクチャ資料は、保存した瞬間から陳腐化する。コード生成ダイアグラム、ADR、自動化されたアーキテクチャテストを使って、資料を正直な状態に保つ方法を解説する。
私がWikiで見たアーキテクチャ図は、すべて間違っていた。劇的に間違っているわけではない。静かに、徐々に間違っているのだ。「Auth」と書かれたサービスは半年前に3つのマイクロサービスに分割された。「sync…