＜ドキュメントの効用＞
ドキュメントというのは、ソフトウェア業界において常に話題の絶えない テーマです。ソフトウェアにおけるドキュメントの重要性は多くの人が認 めていながら、逆にこれを「面倒だ」「無駄だ」と感じる人も多いという 相反するテーマだからでしょう。 これはおそらく永遠のテーマなのでしょうが、私自身の現在の回答を書い きたいと思います。 まず、端的にドキュメントが不要か必要か？の問いには、 「必要」 と答えます。 では、細部にわたる詳細なドキュメントが不要か必要か？この問いには、 「不要」 と答えます。 以下で詳しく追っていきましょう。 −ドキュメントが必要な理由− 現在のプログラミング言語が、処理を記述する言語である以上、ソースコ ードだけ(コメント文を除く)でソフトウェアの仕様を反映することは不可 能です。 (例)バグと思わしき場所が見つかったとき、それが本当にバグなのか、 仕様なのかはソースコードだけでは判断がつかない。 だから、ドキュメントは必要なのです。ただし、コメント文もドキュメン トの一部ですので、コメントをソースコードの一部とみなすならソースコ ード以外のドキュメントは不要という見方もできます。 ソースコードが理想的な落とし込み（「クラスの見極め」を参照）をされ ており、機能単位にわかりやすいコメントがあれば、ある程度はそれも可 能でしょう。しかし、それだけではソフトウェアの全体像をつかむために 全ソースコードを追わねばならなくなります。 それではあまりにも大変です。 また理想的なコード＆コメントでなければコードを追うことすら非常に大 変な作業となることでしょう。 −細部にわたる詳細なドキュメントが不要な理由− ドキュメント必要論を究極レベルにまで高めると、関数の一つ一つ、変数 の一つ一つにまで外部ドキュメントが必要だという見方ができます。 しかし、これはどうでしょう？ このレベルまで外部ドキュメントに落とすということは、 ソースコードの修正 ≒ 外部ドキュメントの修正 (等価) ということになり、常にドキュメントの修正をしつづけなければなりませ ん。しかし、ドキュメントというのは成果物(開発したexe,dll等のファイ ル)に対して何らの影響も与えません。ドキュメントの修正を忘れたとし てもそれに気づかない場合がほとんどです。(だから面倒になって忘れた ふりをする人も現れる) こうしてドキュメントとソースコードは「似て非なるもの」へと変貌して いきます。 「似て非なるもの」になると、それはもう役に立たないドキュメントです。 誰もそのドキュメントを読まなくなります。 細部のドキュメント(関数/変数単位等)というのは、こういう宿命を背負っ たドキュメントだと言えるでしょう。このぐらいのドキュメントは残すに しても外部ドキュメントにせず、ソースコメントで十分です。 さて、ここまで来て残る疑問は、ではどれくらいのドキュメントが適当か？ ということです。 まず、ドキュメントの単位を大雑把に定義してみましょう。 １）外部仕様(ソフトウェア内部構造と無関係) ２）内部仕様(ソフトウェアの機能レベルの仕様) ３）詳細仕様(ソフトウェアの各機能のレベルを落としたもの) ４）クラス仕様(クラス設計にまで落としたもの) ５）関数仕様(メンバ関数のI/Oや内部構造まで設計したもの) １）〜３）は必須でしょう。初めて当該アプリケーションのソースコード を見る人は、このぐらいの前提知識を持った上で作業に望んで欲しいもの です。このレベルのドキュメントはめったに修正されることはありません し、逆に修正されるときはいわゆる仕様変更ですから、ドキュメントに残 すべき内容でもあります。 ４）５）が大きく意見の分かれるところです。 １）〜３）は開発者とは別の部署の人が作業をしたり、開発者のリーダ的 な人が作業をすることが多いのに対して、４）５）は開発者自身が行うこ との多い作業です。基本的に開発者の残すドキュメントは、別の開発者が 理解できるレベルで十分だと思いますので、私的には４）を大雑把なレベ ルで十分(それ以外は必要に応じて)だと思います。 コメントの良く書かれたソースコードにおいて、仕様が分かっていてもな お、不透明なのはクラス間の関連です。主要なクラスに関してクラス間の 関連図を示し、各クラス間がどのように連携して３）の機能を実現してい るか、これが見えてくるドキュメントなら言うことなしです。 (例) [[[ ３）詳細仕様(機能仕様) ]]] 社員情報の表示を行う [[[ ４）クラス仕様 ]]] 以下のクラスを設計し、クラス間の関連を記述 a) 社員データベース b) 社員情報 c) 社員情報表示画面 a)から読み込んだ結果をb)の形で取得し、c)に渡して画面に表示 という意味のクラス図か、それに類するドキュメント このくらいの情報で十分で、それ以上詳細な情報は不要です。 あくまで重要なのはクラス間がどう連携して１つの機能を実現しているか ということです。余分な情報はかえってドキュメントの主たる視点をぼか してしまいます。 ５）のレベルのドキュメントは必要に応じてで十分でしょう。 例えば、社員データベースに関して、内部処理まで書こうとすると、デー タベースのオープン／クローズなども記述せねばなりません。 しかし、データベースを使用している以上、オープン／クローズなんて当 たり前のことです。わざわざドキュメントに残すことではありません。 こういう処理単位の事項は外部ドキュメントはおろかソースコメントにも 不要と考えています。「ソースファイルのコメントに関する規定」の「３． ローカル関数内コメント」を参照。 ただし、セキュリティ管理が必要ならセキュリティ関連の情報(どのユーザ でデータベースにログインするかなど）は必須のドキュメントになってき ます。