プログラムの解説文章をソースコードに混在して表記し、そこから解説記事を生成する、文芸的プログラミングという手法がある。
文芸的プログラミングはソースコードに強く結びついた形でドキュメントを管理することができ、ソースコードの解説を記述するためには良い手法である。ただし、生成される解説記事はあくまでソースコードの記述順に沿ったものであり、プログラマの開発手順、実装順序に沿ったものでは無い。
ソースコードの解説は、そのコードが作られた順番に行われたほうが、プログラマの思考に沿って説明がされるので分かりやすい。そのような発想に基づいて提案された手法が、文芸的コミットだ。
コミットメッセージに、そのコミット内容を説明する文章を記述していくことで、コミットのヒストリーが解説記事になる手法だ。この方式だと、コミットというコードが改変されていく順番で解説ができるので、より分かりやすい内容にできる。
この方式の欠点は、コミットをかなりの注意を払いながら行う必要があることだ。後でその内容を解説記事にすることを考慮しながらコミットするのは、実装する際にかなりの負担になる。解説のために、完成後に改めてコミットを重ねていく方法もあるかもしれないが、それはそれで面倒だ。
なので今回は文芸的diffという手法を考えた。プログラムが出来上がるまでの複数のソースコードをファイルとして保持しておき、それらのファイルに対して解説記事の中からリンクを張る。記事がリンクの部分を表示するタイミングで、そのソースコードと直前のソースコードのdiffを表示する。具体的には以下のような解説記事になる。
このページを下にスクロールすると、画面左の解説に対応する形で、画面右にそれを実現するソースコード断片がdiffとして表示される。さらに、現在のソースコードで実現できる画面が右下に表示される。このようにすることで、実際にプログラムが出来上がるまでの工程を、解説・ソースコード・プログラム動作の3つを並列に見ながら確認できる。
この文芸的diff手法であれば、記事を作る側の負担もそこそこで、ステップバイステップで作り方を説明する記事が作れると思うのだが、どうであろうか。
文芸的diff手法での解説記事を作るためのコードは以下のリポジトリに置いた。
literate-diff-viewerの使い方についてもliterate-diff-viewerで作成したので、参照ください。
