プログラムの詳細のドキュメントは必要か？

プログラムの詳細のドキュメントは必要か？

プログラムを開発する場合、ドキュメントが必要なのは言うまでもありません。プログラムの中身をどのように作るかを詳しく書いたドキュメントいわゆる、設計仕様書は必要でしょうか？この記事では設計仕様書の考え方についてまとめてみました。

プログラムの設計仕様書とは？

最初に、プログラムの設計仕様書とは何かをハッキリさせておきましょう。 これは、プログラムを「どのように作るか（作ったか）」を各ドキュメントです。 プログラムは将来的にも不具合の修正や機能拡張などで、手を入れることも多く、実際にコーディングをした設計者でもその中身の詳細を覚えていることは難しくなります。多くの場合は、最初のコーディングをした人と別の人がプログラムに手を入れる事も多いので、プログラムがどのように作られているかを書いたドキュメントがないと、コードを読みながら理解して修正する事になるので効率が悪くなります。従って、きちんと設計仕様のドキュメントを残すことはとても重要です。

操作の説明（取り扱い）のドキュメントは、利用者のためのドキュメントですが、設計仕様書の場合は、プログラマーのためのドキュメントという事になります。従って、内容は専門的で問題ありませんが、プログラムがどのように作られているかを分かりやすく書く必要があります。

操作の説明と詳しい設計仕様はどっちが大切？

会社などでプログラムを開発する場合は、操作の説明のドキュメントも、設計の仕様書も両方きちんと作ることが求められます。当然と言えば当然ですが、フリーランスの場合は、短期間での開発を求められる場合も多く、時間との兼ね合いで両方作成する時間がない場合もあります。

その場合は、どちらのドキュメントが大切かというと、個人的には「操作の説明のドキュメント」だと思います。 理由は簡単で、前回の記事で説明した通り、この操作の説明は、利用者だけではなく、プログラムの開発者にとってもとても役に立つドキュメントだからです。プログラムの設計方針を決める助けにもなりますし、テストの計画にも利用できるからです。

しかし、設計仕様書がなくても良いという話には通常はなりません。やっぱり設計仕様書も必要です。 この記事で紹介したいのは、最低限の設計仕様には何が必要かです。

実は、最低限必要な事を書けば、大抵のプログラムの発注先の方は受け入れて頂ける場合が多くなります。

プログラムにはソースコードがある！

設計仕様書を簡単にできる理由は、プログラムの場合ソースコードがあるからです。 通常、委託されてプログラムを開発する場合、開発したプログラムのソースコードも一緒に納品するのは普通です。

実は、プログラムの詳細はソースコードなので、ソースコードを提出すれば、仕様書に細部まで書かなくてもどのような設計かが分かります。そこで、ドキュメント作成の時間を削るために、ソースコードの書き方を工夫することで細部の説明を避けるという考え方があります。

そのために必要なことは、二つです：

1. コメントをできるだけ入れてプログラムの詳細の説明を書いておく

2. できるだけ読みやすいコードを書く

コードを手直しする場合は、ソースコードは必ず見ます。従って、詳細の説明はコメントに残した方がソースコードを読む効率もアップします。従って、重複する情報は設計仕様書からは省いてしまうと、設計仕様書も実は読みやすくなります。

読みやすいコードというのは、多少行数が増えても、分かりやすく書くことです。 まとめて長い条件や式を書くのではなく、意味がある名前の変数に代入するなどして読みやすくするための工夫をする事が重要です。 多少、書き方によって処理が遅くなったり余計なメモリを使う場合もありますが大抵は大きな問題にはなりません。

トリッキーなコードを書くより自然で見やすいコードにすればドキュメントやコメントの手間も少なくてすみます。

設計仕様のドキュメントには何を書くか？

では、設計仕様のドキュメントには何を書いたら良いでしょうか？

書く内容はソースコードからは分かりにくいことを中心にまとめます。

具体的には、「全体」と「インターフェース」です。

全体というのは、沢山あるソースコードの関係とグループ分け機能などです。 各コードの具体的な機能（何をするか）と、関数や API のインターフェース、要はどんなデータを渡して、処理結果としてどんなデータを受け取るかです。

もう一つ大事なのは、処理の流れとデータの流れです。これはソースコードを見ただけでは分かりにくい部分なので仕様書に書きます。

ドキュメントには、ソースコードの一覧を書いて、機能の概要をまとめます。機能の概要は、利用する関数や API のインターフェースの仕様を書きます。各処理の具体的な内容はソースコードやそのコメントを参照するような記述を書いておけば OK です。

あとは、処理やデータの流れをフローチャートなどにして、全体の関係を記述しておけば、最低限必要な設計情報はカバーされる事になります。

あとは、いつドキュメントを作成するかですが、これもコーディングをする前に書いておくとプログラムの設計やインターフェースが明確になるので、プログラムのコーディングも効率的になりますし、バグも少なくなる場合が多くなります。

まとめ

プログラム開発でドキュメントの作成はコーディングと並んでとても大切です。 しかし、フリーランスのように自分自身で全ての作業を行わなければならない場合は、会社でプログラムを開発する場合のような完全なドキュメントの作成は難しいのが現実です。

このような場合は、ソースコードを読みやすくコメントの多いものにすることで、ドキュメントに書くことを厳選して作成するようにすると効率よくプログラムのコーディングとドキュメントの作成が可能です。

ドキュメントの作成をコーディング前の行うことで、コーディングの見通しも良くなり、バグの少ないプログラムにすることが容易になります。

設計仕様には、ソースコードからは分かりにくい情報、「全体」と「インターフェース」を中心に、処理とデータの流れをまとめるとプログラムの設計が分かりやすくなります。設計仕様に、各処理の内容の詳細までを記述しようとすると結構な作業になりますが、重複する部分をなるべく作らないような記述を意識すると、作業量をかなり減らすことができます。

フリーランスの場合は、上手く作業量を減らす工夫が必要です。作業量を減らしても、全体の品質を下げないことを上手く発注先の方に説明できると大きな信頼も得られます。