実装が終わってからプログラム説明書を書こう

設計書と説明書は同じもの!?

一般的な開発手法では、はじめにソフトウェアの設計を行い、設計書を作成する。ここで提案する手法では、更に、実装の後にプログラム説明書を作成する。

これらはいずれも、ソフトウェアがどのような作りになっているかを解説するドキュメントである。よって、この２つのドキュメントの内容は、まったく同じになる。

では何故、はじめに設計書を作っているのに、改めて同じ内容の説明書を作らなければならないのだろうか。

設計書と説明書では、読み手が異なる

実装の前に作成する設計書とは違って、プログラム説明書は実装の後で、完成したソフトウェアを元に作成する。同じプログラムの作りを解説するドキュメントであっても、実装の前に書くのと後に書くのとでは、出来上がる文章は、まったく別物になる。

設計書は、これからどのように実装するか、その指針を書いたものである。つまり、実装を行う自分自身のために作るドキュメントである。一方、プログラム説明書は、将来このソフトウェアに関わるであろう新しい担当者のために、ソフトウェアの作りを説明するためのドキュメントである。

設計書のレビューも行われるが、そこでは主に、設計の善し悪しが検討される。設計書の文章が分かりやすいものになっているかどうかは、あまり考慮されることはない。例えば、設計書の文面では、設計に関わったメンバーだけに通じるスラングや、内輪の概念が使われることがある。

顧客は、第三者でもソフトウェアの作りを理解できるように、ドキュメントを要求する。顧客のニーズに適しているのは、開発者のために書かれた設計書ではなく、他人に説明するために作られたプログラム説明書の方だ。

但し、これだけなら、単に文章の表現上の違いだけである。ところが、実際の設計書と説明書とでは、本来は同じになるはずの内容が、違ったものになってしまうことも多い。

設計書は、ソースコードの作りと乖離しやすい

本来であれば、いったん設計書を完成させたら、実装では設計書の通りにソースコードを書いていくだけで済むはずだ。だが現実には、さまざまな理由により、設計書の通りには実装されないことが多い。

例えば、利用するライブラリのAPIの都合で、呼び出し側の仕組みを変えなくてはいけないこともある。または、設計書の通りに作ったら不具合が発生したため、回避策を講じなくてはならないこともある。経験の浅い開発者ほど、このような状況が起こりやすい。

プロジェクトによっては、設計フェーズでは概要設計までしか行わず、詳細設計を端折ることもある。その場合、設計書に書かれている概要レベルのモデルから、ソースコードレベルの詳細なモデルに変換する作業が、実装フェーズで行われる。その結果、設計書の内容とソースコードの作りに、食い違いが生じることになる。

こうした食い違いが積み重なって、設計書の内容は、実際のソースコードの作りから乖離してしまう。そして、設計書からソフトウェアの作りを理解するのは難しくなる。実装の後に書くプログラム説明書なら、このような問題は発生しない。

機能追加をするたびに、設計書は増えていく

実際のソフトウェア開発では、たびたび機能追加が繰り返される。

機能追加のためにソフトウェアを改造する時は、元の設計書に加筆修正するのではなく、新しく改造設計書が作られることが多い。改造設計書では、追加する部分と、それに伴って変更される部分についてのみ記述される。

何度も機能追加を繰り返すたびに、改造設計書は増えていく。その結果、次の担当者は、過去のすべての設計書、改造設計書に目を通さなくては、今のソフトウェアの作りを知ることができなくなってしまう。

これは大変な作業だ。単にドキュメントの数が多い、というだけでなく、歴代の開発者たちの思考の道筋をすべて辿り直して、過去の改造の履歴から最新の状態を作り上げなくてはならないためだ。新しい担当者は、最新のソフトウェアの作りを知りたいだけなので、これは明らかに無駄な知的労働である。

一方、プログラム説明書は、実装の後に作るものである。機能追加の際は、改造の後に、プログラム説明書を書き直すことになる。そのため、新しい担当者は常に、最新のソフトウェアの作りを直接に知ることができる。

設計書をメンテナンスするくらいなら、新しい説明書を書こう

プログラム説明書を作る上での最大のネックは、一般的な開発手法に対して、工数が余分に増えることであろう。

だが、設計書だけを残すとしても、実装フェーズで発生した食い違いを設計書に反映する、という作業は、いずれにせよ必要となるはずだ。

ところが、一般的な開発手法では、実装フェーズの後はテストフェーズとなり、ドキュメントを書き直す作業は、予定の工程には入っていないことが多い。余分な作業と見なされるため、モチベーションは低くなり、スケジュールによっては省かれてしまうことも多い。その結果、実際のソースコードの作りと乖離したままの設計書が残されることになる。

仮にきちんと工数を取り、設計書を書き直すとしても、その作業は容易ではない。実装フェーズで発生した食い違いをきちんと書き残していなければ、設計書とソースコードをすべて見比べて、差分を洗い出さなければならない。

プログラム説明書を作らないとしても、ドキュメントを書き直す工数は必要となる。また、書き直すためには、実装が終わってからソースコードを見直さなければならないことも多い。そこまでするのであれば、結局はプログラム説明書を作った方が早い、という結果にもなりかねない。

説明書を作ることで、Plan-Do-Seeが実践できる

プログラム説明書を書くとなると、実装が終わってから、一通りソースコードを読み直さなければならない。これは、出来上がったソフトウェアの作りについて、自分で評価することに繋がる。

モノ作りでは、Plan-Do-Seeのサイクルが大切である。ソフトウェアの開発では、設計がPlan、実装がDoに当たる。しかし、技術者としてのスキルアップを図るためのSee（評価）は、ほとんど行われていない。

一般的な開発手法では、実装の後にはテストとデバッグを行う。これらは、ソフトウェアの品質を上げ、顧客の満足度を上げるためのものだ。技術力を向上させるために、開発者自身のために行うSeeのプロセスは、開発工程の中に組み込まれていない。そのため、ソフトウェアの開発者は、業務経験を積んでもなかなか技術力が向上しなかった。

プログラム説明書を書くために、ソースコードを見直すことは、スキルアップのためのSeeのプロセスに当たる。つまり、プログラム説明書を作るようにすれば、開発工程の中で、開発者のスキルアップが図れるようになる。

書く、という作業で、設計上の問題点が浮かび上がる

ソースコードを見直す、と言っても、経験の浅い開発者では、問題点や改善すべき点を洗い出すことは、意外と難しい。プログラムはきちんと要求仕様どおりに動いているため、ソースコードをただ眺めていても、問題点がないように思えてしまうのだ。

プログラム説明書というドキュメントを書くことは、ソフトウェアの設計上の問題点を浮かび上がらせるのに、たいへん有効な手段でもある。文章にまとめ、他人に説明をしなければならないために、ソースコードを分析的に眺めることになるためだ。例えば、ソフトウェアの作りを説明しようとした時、うまく章や節を分けられなかったり、余分な制約や注記・例外などを書かなくてはならなくなって、はじめて設計上のまずい点に気づく、ということもある。

設計上の問題点に気づきやすくするためには、プログラム説明書を書く際に、ソフトウェアのありのままの姿を書くだけではなく、何故そのような作りになっているのか、背後に潜む理由も合わせて書くようにすると、より効果的である。

プログラム説明書は、リファクタリングよりも現実的な方法

最近では、ソフトウェアの実装が終わった後で、リファクタリングを行うことも多くなっている。ソフトウェアの作りを見直して問題点を洗い出し、機能はそのままに、必要に応じてソフトウェアの改修を行うのである。これも、Plan-Do-SeeにおけるSeeのプロセスの１つである。

リファクタリングでは、完成したソースコードに手を加えるため、実施するには抵抗も大きい。また、改修したソフトウェアの再テストも必要になるため、余分な工数がかかりすぎる、という問題もある。テストの自動化も必須であるが、不可能な場面も多い。結局、実際の業務では、あまり現実的な方法ではない。

プログラム説明書を書く方法は、ソースコードを見直して問題点を洗い出し、どのようにすれば良いかを見極めるまでに留める。そのため、実際の業務でも実施しやすい。