開発ポリシー
ソフトウェア設計書は書くべきか
私は職業柄、いろんなソフトウェア開発の現場を見てきました。
その経験で強く思うのは、まともな設計書作成ができる、あるいはやろうとする組織が極めて少ないということです。
まあ、ソフトウェアによっては設計書は不要というものはあるでしょう。
ただ、大部分のソフトウェアはバージョンアップなどの保守がつきものです。
よほど小規模のソフトウェアでない限り、その時になって困ることになります。
機能拡張や保守のために、多大な労力を費やしているところが非常に多いと感じています。
ここで、
多大と言っているのは私の目から見ての話で、実際に作業している人物にはその意識がないのかもしれません。
効率的な組織を見た経験がないためにソフトウェア開発とはこんなもんだと思っている、
あるいは前任者がやったことだから仕方がないと諦めています。
本当にしょうがないんでしょうか。少なくとも自分ができるところから始めれば…と思います。
こういうことを言うと、役にも立たないドキュメントを無理やり作らせる、口やかましい品質保証部門の人間のような印象を持たれるかもしれません
(すみません、私、実際に品質保証部門にいたこともあります)。
決してそういうことではなく、不要なものは作成しない、本当に必要な文書のみを着実に作成するということです。
その意味で、私のポリシーには以下に示すように一見相矛盾するように見えます。しかし、良く読んでいただければおわかりいただけるかと思います。
■ ソースにコメントは書くな
ソースにコメントを書くより、わかりやすいコードを心がけることが第一です。余計なコメントがあっても、読みにくくなるだけです。
- 変数名やメソッド名は、見ただけでその用途や機能が推測できるようなものにする。
- トリッキーなロジックは避けて可能な限りシンプルにする。
- オブジェクト指向言語であれば、できるだけシンプルでコード実装量が少なくなるようなクラス体系にする。
■ ソースにコメントを書け。ソースコードもドキュメントだ
いくら、変数名やメソッド名をわかりやすくしたとしても、それはミクロの観点からわかりやすくなるだけにすぎません。
コードのみのソースでは、保守の場合、クラスの役割やメソッドの使い方などを知るために、コードを逐一読まなければなりません。
多くの組織でこれに多大な労力を割いており、非効率極まりないと感じている点の一つです。
細かいレベルのコメントは良く見るのですが、大局的なコメントを確実に書いているものは非常に少ない。
私はまったく逆だと思います。実際、言葉で同じことを言っている人は多いです。
しかし、実践できている人は非常に少ない。
私は、クラスの役割や目的、他のクラスとの関係を記述したクラスコメント、および
メソッドの目的、機能、引数の使い方、戻り値の意味、その他注意事項は、確実に書くように心がけています。
どんなレベルまで書くべきか、私は、自分自身が1年後にこのソースを見たときに欲しいと思うかどうか、ということを想像しながら判断しています。
■ 設計書は書くな
意味のないドキュメントを作成しても、労力を無駄に費やすだけです。
また、ソースコードとは別にドキュメントを作成しても、メンテナンスが大変で、すぐにソースとドキュメントが乖離してしまいます。
乖離したドキュメントに価値はありません。労力を無駄に費やすだけです。
必要な情報は、別ドキュメントではなくソースコードにコメントとして書くようにしましょう。
ソースコードであれば、コードを改編するのと同時にコメントも書き換えるのは容易です。
もちろん、それを貫く意志が必要ですが。
■ 設計書を書け
必要な情報は、ソースコードに書こうとしても限界があります。
プログラムやシステム全体の構造、アーキテクチャに関する内容は、ソースファイルには書く場所がありません。
このような情報こそ、別ドキュメントとして作成しましょう。
このような情報はそれほど頻繁に修正が入るような性格のものではありません。保守に多くの労力をとられることは少ないでしょう。
これらの書き方のテクニックを学ぶことも重要です。へたに作ればあまり効果のないものになってしまいます。
最近はUMLが流行しています。UMLも役立ちますが、私は構造化技法を学んだ後にUMLを学んだ方が良いと考えています。
構造化技法に触れると長くなるので別講に移すことにし、私が非常に優れていると考えている参考文献をあげておきます。
ソフトウェア構造化技法 (ダイアグラム法による) J.マーチン・C.マックルーア著 邦訳版: 近代科学社
各種ダイアグラムは、UMLへ至る前身のようなもので、UMLだけを学ぶよりずっと多くのことが学べます。