ドキュメント

ドキュメントの種類

基本設計書

画面遷移、大まかなデータの流れなど。

機能設計書

画面のボタンや入力項目の入力値制限など。詳細な仕様。基本設計書の中に含めてしまうことも。

詳細設計書

画面単位でのシーケンス図は絶対必要だと思う。将来システムをメンテナンスするプログラマのことを考えて作ること。

ユーザーマニュアル

エンドユーザー向け。

管理者マニュアル

運用・管理するためのノウハウ。トラブルシューティング。過去のトラブルの記録の所在。

DB設計書

テーブル等の仕様。単にテーブルやカラムのデータを載せるだけでなく（そんなものはコマンドを使えば調べられる！）、そのテーブルの使用目的も書くこと。

納品物ではなくても必ず作るべきもの

用語集

そのシステム特有の概念を説明したもの。

参画マニュアル

プロジェクトに新規参画するひとのためのもの。
開発環境構築手順、システムの概念、コミットやデプロイ等の手順、ドキュメントの所在等。

雑感

仕様書の本文とその変更履歴は分離すべきだと思う。変更箇所に打ち消し線を引いて、「Version xxより変更。○○を参照」などと書いていくと非常によみづらい。

打ち消し線があっても読者は無意識にその下にあるテキストを読んでしまう。その後「これは打ち消されているから不要な情報なのだな」と判断し、さらに新しい情報を探して読むというプロセスをたどることになる。これは読者に対し意識的／無意識的に多大なストレスをかける。

「打ち消し線を使わず消してしまうと、どこが変更されたのかわからなくなってしまう」というかもしれない。しかし変更を管理するという目的のためには打ち消し線は不十分である。
例えば、変更前の仕様が以下の通りであるとする。

CSVファイルをインポートすると現在画面に表示されているデータは上書きされる。

これを次のように変更したとする。

CSVファイルをインポートすると現在画面に表示されているデータは上書きされる。

ただし、No. 1から No. 18 までは上書きされない。

どうだろうか。文章変更は追記だけだが、意味的には以前の内容の一部を打ち消している。つまり、追加部分もわかるようにしなければ変更管理として十分ではない。
しかしわざわざそんな手間をかけて文書を読みづらくする必要はない。MS-Word には「変更履歴を記録する」という機能が備わっているのでこれを使えばよいのである。

Javadocコメント

Javadoc形式で書く。
Javadocを利用できない言語の場合でも、@paramなどの記法を使うこと。

・param, returnは必須。
・できる限り使用例を書く。
・数値のとりうる範囲が決まっている場合は明記する。

	range[0,10]    0以上10以下
	range[0,10)    0以上10未満
	range(0,10]    0より大きく10以下
	range(0,10)    0より大きく10未満
	(> 0)          0より大きい。
	(<= 10)        10以下。

例：

/**
 * 指定した日の曜日を返す。
 *
 * <pre>
 *   getDay(2008,4,1) => 2
 * </pre>
 * @param y	年 range[1970,2038]
 * @param m	月 range[1,12]
 * @param d	日 (>=1)
 * @return 曜日（0:日曜 ... 6:土曜）
 */
function getDay(y, m, d) {
	...
}

※使用例をあまり詳しく書くと、ユニットテスト（JUnitなど）と重複するのではないかという気がしてくる。コメントとユニットテストを同期させるいい方法はないだろうか。