仕様書・自動化テスト・実装の三位一体開発

タイトルは最近考えてることでしてね。ちなみに最初に申し上げておくべきことは、以下に書くことは、仕様を決める権利・スケジュールを決める権利・開発方法を決める権利を自らが持っている開発チーム及び開発者を対象としている、ということです。ということは受託開発よりも、自社サービスや自社製品の開発あるいは社内システム開発という立場向け、ってことです。

言いたいことを一言で言うと、仕様書・自動化テスト・実装を行き来しながら少しずつ作っていく、ということです。例えば、仕様書に少し書き加え、該当する自動化テストを少し書き、さらに該当する実装を少し書く。それを小さいサイクルで繰り返していく。というふうに。

もちろん、例えば実装方法に依存して考えなければならない部分があったりして、先に仕様書が書けない場合なんかもありますけど、その時は実装を先に書いてもいいわけです。その代わり可能な限り早く仕様書に反映し、該当する自動化テストも書くようにします。つまり、どれか１つだけが大きく突出しないようにします。

これの一部だけを取り出すと、自動化テストと実装の部分だけ見れば「テスト駆動開発」になるでしょう。さらに自動化テストの範囲が広がって振る舞いや挙動の記述も含むようになれば「ビヘイビア駆動開発」となりますね。

もし仕様書だけを集中して先に完成させてしまうと、いわゆるウォーターフォール型になります。あるいは仕様書も一緒に作っていくという概念を抜かせばアジャイルになります（大雑把に言えば）。

なお、「◯◯駆動開発」と呼んでしまうと、その「◯◯」を原則として先に作らなければならないということになりますが、仕様書・自動化テスト・実装は常に順番を固定して作れるようなものではなく、むしろお互いを行き来しながらバランスを取りつつ進めていく、という表現がしっくりきます。その上で、理想としては「仕様書→自動化テスト→実装」の順番のサイクルを維持する、と思っておけばいいと思います。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうぞ。

エンジニアの差は「最後のツメ」に出る

設計書とかプログラミングとか、エンジニアの成果物にはクオリティが求められますけれども、結局のところどこに差が出てくるかというと、いわゆる「最後のツメ」ってやつですよね。

頻度は少ないものの重要なユーザの操作に対するちょっとした仕様の工夫だったり、万が一のための例外処理で最悪の事態を避けるものだったり、ハッキリ目に見えて分かりやすいものでは無いかもしれないですけれど、「何かあった時に違いが分かる」ってやつです。

しかしまあ、そういう「最後のツメ」のクオリティを上げるっていうのは、義務感とかじゃ無理だと思うんですよね。僕は、「こだわり」だと思うんですよ。気になって仕方ないっていう感覚のほうが、正しいと思うんです。

ちなみに、この最後のツメをしつこく追い求めていると、結局１時間で終わるはずだった作業が２時間もかかってしまったりします。しかし、最後のツメを甘いままに作業を終わりにしてしまったら、例えば後になってミスが発覚し、しかもその前提で進めてしまった別の作業の部分も併せて修正を入れるはめになり、結局トータルで４時間かかったりするのですよ。

決して分かり易くないけれど、やっぱりそういう差ってあると思うんですよ。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうぞ。

ドキュメントはいつ書き、いつ修正すべきか

アジャイル開発の有名な指針には「詳細なドキュメントより、実際に動くコードを優先する」というものがあり、その影響かどうかは分かりませんが、開発中にドキュメントを書かないプロジェクトも多いと聞きます。

そもそもアジャイル開発の対局にあるウォーターフォール型の開発であったとしても、一度フィックスしたドキュメントを修正するのは容易ではなく、一度設計プロセスを通過してしまったプロジェクトではドキュメントの修正は後手に回ってしまいやすく、結局誰も見ないという事態が発生しがちです。

こういう問題は一概に答えを出すことは難しいものですね。以下の文章は、１人〜数人程度のチームで小規模開発を行う場合に限定した意見として読んで頂ければ幸いです。

ドキュメントを最初に全部作ってフィックスさせてしまうのも、あるいは開発中ほとんど（あるいは全く）手を付けずに、最後になってコードに合わせてドキュメントを作るのも両方良くないと思います。もちろんそんなことは分かっていると仰るでしょうが、実際のプロジェクトでは特に後者のパターンは結構頻繁に行われていますよね。

ドキュメントを書く利点の１つは、コードを変更する手間よりもドキュメントを変更する手間のほうが少ないため、いきなりコードを書いてしまってから修正するよりは効率よくデザインが出来るということです。しかしながら、逆にドキュメント上だけで実際のソフトウェアの詳細な動作や操作感を想像するのには限界があり、ドキュメントを詳細に作りすぎると今度は実際その通り作ってみたら期待と違った、なんてことも起こります。

だから考え方としては
「難なく想像できる詳細度まではドキュメントのみを先に書き、それより詳細な部分のドキュメントは開発しながら書く」
という感じがいいのではないかと思ってます。

例えばWebアプリケーションで言うと、画面遷移や画面のざっくりした大まかな構成はコーディングを初める前に書き、それより先はコーディングを進めつつ書く、みたいな感じですかね。

ドキュメントの更新を最後にまとめてやるパターンは実に多いんですが（そして気持ちもよく分かりますが）、ひたすらドキュメントだけを作るのは大変で退屈な作業である上に抜け漏れも発生しやすいので、やはり開発中に頻繁に更新すべきでしょうね。

理想的には「ドキュメント駆動」的な開発ができるといいと思ってます。まずドキュメントに変更を加え、それに基づくテストを書き、それから実装コードを書く、っていう手順です。現在僕が取り組んでいるプロジェクトではこの進め方を実際試してみるつもりで、このテーマについてはまた書くと思います。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。

いつでもプロジェクトを引き継げるように意識する

まだプロジェクトの初期段階で、画面設計やらフレームワークの準備も手を付け始めた所ですけれども、僕が最初から意識しているのは「いつプロジェクトを別の人に引き継ぐことになってもいいようにする」ってことです。

それは例えば、僕の頭の中にしか無い事柄をなるべく少なくするということ。つまり必要事項をきちんと文章に残すという意味です。もちろん、全てのノウハウを書く時間の余裕はないですけれども、例えばネットで調べればそれほど苦労せず辿り着くようなことは書かなくていいわけで、そうではなくて僕がメモを残さないと、ネットで調べても意味不明になってしまうようなことに関しては、きちんとメモを残すということです。

他にも例えば、情報が分散しないようにすること。あることについて書いたドキュメントが複数の場所に散らばらないようにしますし、もしどうしても場所を分散する必要があるなら一箇所のファイルにどの情報がどの場所にあるのか一覧をつくります。

ドキュメントだけでなく、プログラムの構成もそうですね。見通しを良くするというと。例えばファイルの命名規則やディレクトリ構成を、初めて見た人でも分かりやすいように意識します。標準的によく使われる構成があるならそれに従うようにします。それでもわかりにくいようなら、ドキュメントに一言メモを書いておきます。

もちろん、本当に今からいきなりプロジェクトを引き継ぐことになる可能性は低いわけですけれども、いつでも引き継げるような体制をとることは、様々なメリットを生み出します。自分でもプロジェクトの細部に渡るまでしっかり把握するよう意識しますし、抜け漏れやあやふやな点もないように努力もしますからね。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。

画面仕様書にはどこまで詳細を書くか

仕事でソフトウェア開発をしていて仕様書を書いてますけれども、今週から画面設計の部分にとりかかりました。そこで考えるのは、仕様書に画面設計の詳細をどこまで書くか、ということです。

以前仕事をしたある職場では、画面仕様書に関係する関数名や変数名の一覧まで書いてありましたけれども、ちょっとそこまでやるのはやり過ぎだと思います。実際コードを書く際にいくらでも変更される部分ですし、いちいちドキュメントを修正していたら手間がかかりすぎてそのうち仕様書を見向きもしなくなるでしょう。

逆に、以前アジャイル開発をした時は画面設計というはむしろ仕様書自体、開発中は全く手を付けていなかった状態でした。それはそれで最後に時間がなくなり、結局まともな仕様書を残すことはできませんでした。まあ、それは仕様書を残す必要のない性質のプロジェクトだったからよかったものの、そうでなければ少々まずい事態でしたね。

その辺の落とし所は一概にこうすればいいというものではなく、プロジェクトごとの個々の状況に応じて変わってくるんだろうなと思います。今回の僕の方針としては、機能を文章で説明しつつ、ごくごく簡単なワイヤフレーム（白黒で装飾の全くないもの）でボタンやテキスト等の要素の配置を示すことにしたいと思ってます。詳細に立ち入りすぎず、かつ機能の説明を最低限のラインで果たしているという感じを目指します。

あえて、「全ての機能を完全に」書くのではなく、文章の文脈や図などを見れば必然的に想像できることについては記述を省略する・・・って構成にできれば理想的です。この加減や方法については今後も研究していきたいと思います。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。

ドキュメント管理のためSphinxを導入してGitで管理

ソフトウェア開発においてはドキュメントの変更は頻繁に起こるものです。といいますか、「起きるようにすべき」ってことなんですがね。

ドキュメントの更新は得てして（非常に高い確率で）放置されがちなタスクです。古くなってカビとキノコが生えたドキュメントは役に立たず、誰からも参照されなくなります。そして、リリース直前になって慌てて開発チームが更新作業に追われるのですね。

昨今ではすっかり市民権を得た（と少なくとも見える）アジャイル開発においても、「ドキュメントよりも動くソフトウェアを重視する」という方針のおかげか、ドキュメントは開発中は手を付けず、最後にまとめて作るやりかたも実際に行われてるという話も聞いたことがあります。

僕自身、アジャイル開発を本格的に行った以前のプロジェクトにおいては、開発中にドキュメントは作りませんでした。しかし考えてみれば、そのプロジェクトはWebサービスの開発であって、誰かに仕様を1つにまとめて伝える必要性がそこまで高くないものだったのです。しかし今取り組んでいるプロジェクトは製品として外部に出荷することを想定しており、その意味では仕様をまとめる必要性があります。

しかし、最後にまとめて変更するやり方ではそもそも大変ですし、ミスも生まれやすくなります。何より、ひたすらドキュメントの更新をするのはあまり楽しい作業ではありません。やはり、ドキュメントを開発にともなって随時変更していきたいところです。しかし、それは放置されがちになることは既に述べました。

プログラムのソースコードがなぜアジャイル開発のような頻繁な変更にも耐えられるのかといえば、SubversionやGitのようなバージョン管理システムの貢献が大きいです。コードのどの部分がいつ誰によってどう変更されたのか明確に把握できてこそ、一度書き上げたコードの一部をかいつまんで変更し続けることが容易になるのですね。そうでなければチームは大混乱に陥ります。その意味で、バージョン管理システムが発達していなかった時代、ウォーターフォールしか選択肢がなかったのも頷ける話です。

つまり、ドキュメントの変更を開発に伴って頻繁に行うには、どの部分がいつ誰によってどう変更されたのか把握できるようにしなければなりません。残念ながらExcelやPowerPointではこのことは実現が非常に困難です。

だったら、もしバージョン管理システムによってドキュメントを管理できれば、開発しながらドキュメントも書くということが実現できそうです。そのためには、ソースコード管理システムによって変更を把握できる形式、すなわち「プレーンテキスト」である必要があります。

そこでプレーンテキストからドキュメントを生成する仕組みを導入すればいいと気づくわけですね。有名なものに科学論文向けのTeXがありますが、ソフトウェアのドキュメント向けに開発されたツールの1つとしてSphinxがあります。SphinxはPythonの公式ドキュメントに使われている他、多くのマニュアルやサイトに使われています。

なんか前振りだけで長くなりましたが、まあこういったツールの導入には考え方が重要ですからよしとしましょう。手順自体は大したこと無いんで、簡潔にまとめます。環境はDebian Linuxです。

まず、Sphinxをインストールします。Pythonは既にインストールされているものとします。Debianのパッケージは古いので、公式リポジトリからソースをダウンロードして使います。

$ wget https://bitbucket.org/birkenfeld/sphinx/get/1.2.1.tar.bz2
$ tar jxvf 1.2.1.tar.bz2
$ cd birkenfeld-sphinx-3238dc3d4528/
$ python setup.py build
$ su -
# python setup.py install
# exit

これで/usr/local/bin以下に実行ファイルがインストールされます。次に、ドキュメント管理用のGitリポジトリを用意し、その中でsphinxプロジェクトを初期化します。

$ mkdir foo-doc
$ cd foo-doc
$ git init
$ sphinx-quickstart

sphinx-quickstartを実行すると、幾つか質問されます。その際、プロジェクトの名前と著者名（複数可）だけ答えてあとはデフォルトでいいという説明をよく見かけますが、こんかいはGitで管理する都合上、ソースと生成したドキュメントを分離することにします。以下の質問をされた時に y と答えればいいです。

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

これでSphinxでドキュメントを作成するための基本のファイルが生成されます。 .gitignoreでbuildディレクトリを除外しておきましょう。ドキュメントのソースコードはsource ディレクトリ内にあります。ドキュメントを生成するには、Makefileのあるディレクトリで

make html

などと打てば生成されます。html以外にもpdfなど様々な形式を指定できます。具体的なドキュメントの書き方の詳細については日本ユーザ会のマニュアルなどを参照ください。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。