良いソフトウェアに求められる３点セットとJSXの開発手法の改善とgit-pushdirについて

テスト駆動開発（TDD）の一般化とGitHubの登場によって、機能追加の際にコードとテストを同時に実装する（そして、両者を一括してmasterにmergeする）という開発手法が一般化してきました。

しかし、「良いプログラム」の要素を構成するのは、コードとテストのみではありません。動作するコードと、その品質を担保するためのテストがあったとしても、適切なドキュメントがなければ、ユーザーはそのプログラムをどうやって使ったら良いかわかりません。

つまり、ユーザーに使いやすいプログラムを継続的に開発／提供しようと思うと、

• コード
• テスト
• ドキュメント

の３点セットを提供する必要があるのです^注1。

今日のJSXが抱えている最大の課題は、ドキュメントが不足しているという点にあります。その原因は、「機能追加」の際にコードとテストのみを実装してmasterにmergeすることを繰り返す一方で、ドキュメントはプロジェクトページのレポジトリとして別個に更新作業を行ってきた^注2点にあり、その結果、コードとテストは存在するが対応するドキュメントがない機能がいろいろ実装されてきてしまった、と認識しています。

以上の認識に基づき、JSXのプロジェクトページにあった文書を全てJSX本体のレポジトリへ移動しました。今後は、

• プルリクエストはコード／テスト／ドキュメントの３点セットで構成すること^注4
• そのために、すべてのドキュメントをレポジトリ本体の一部として管理すること

という形で運用していきたいと考えています。

また、この目標を実現するために、git-pushdirというスクリプトを書きました。このスクリプトは、あるディレクトリの中にあるファイルを丸ごと、指定したGitレポジトリにpushすることができます。JSXではこのスクリプトをMakefileから以下のように呼び出すことで、リリースの際に自動的にプロジェクトページのドキュメントを更新するようにしました。

publish: publish-test
        npm publish
        $(MAKE) doc-publish

doc-publish: doc
        (cd doc/jsx.github.com && ../../tool/git-pushdir -m "`git log --format='doc at commit %h' | head -1`" git@github.com:jsx/jsx.github.com.git)

似たようなことはgit subtreeを使っても可能^注3ですが、subtreeの定義やpullした場合のconflictに絡む問題がない点がgit-pushdirの優位性になるかと思います。

つーことでよろしくお願いします＞関係者諸氏。

注1: テストを書くコストが見合わない、あるいはドキュメントなど不要というケースもあるとは思います
注2: jsxdoc（javadocライクなツール）が出力するAPIリファレンスではなく、言語仕様に関わる文書のようなものについて述べています
注3: 参照: git subtreeで自動生成ドキュメントをGitHub Pagesに連携してみた - Life goes on
注4: コードとテストのレビュー完了 → ドキュメント加筆更新 → merge というフローでいいと思います