Friday, May 9, 2014

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


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

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

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

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

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

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

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

  • プルリクエストはコード/テスト/ドキュメントの3点セットで構成すること注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 というフローでいいと思います

1 comment:


  1. Media followed suit because it was media that omega replica watches helped create this less nerdy side to watch appreciation. Watches suddenly went from being a very personal thing you bought as part of rolex replica your lifestyle to something which is about showing off. In a sense, this was a market necessity because watch companies needed to create desire in one key demographic: the ultra fake breitling rich. Who do you think are buying $50,000 and over watches. While the watch industry loves to share their new $500,000 rolex replica sale watches with the world, it is sometimes a crap shoot who ends up buying them. Then again, watch companies have faced the economic reality that in order to make money, they need to fake rolex find a handful of people to buy $500,000 watches, versus a lot of buyers to buy $1,000 rolex replica uk watches (as was the case a few decades ago).

    ReplyDelete