無駄な設計書をなぜ書かされるのか・なくすにはどうしたらいいか、に関する乱文

コードを日本語訳したような設計書。CREATE TABLE 文を表形式に変換した定義書。これらは「Excel 方眼紙」と呼ばれる日本の SE 業界を象徴する伝統的な手法で記述されており、ロクにメンテナンスされることなく引き継がれ、保守担当者を困惑させる。

今回はこうした設計書がなぜ存在し、どうしたらこんな醜いものをなくせるか、考えたい。

対象とするのは、ブラウザからアクセスできる、Web アプリケーションとして動作する社内のアレコレを管理するようなシステムを作る場合。組み込み系などは経験ないので、ソフトウェア開発における話、それもインターネットに繋がっていない環境で仕事をさせられているような時代遅れの SIer に限定させていただきたい。

漠然と思った順に書き殴っていくので、乱文です。

自分の基本主張

保守担当者として思うこと

自分が着任するより前から、ドキュメントがロクに保守されていない状態で引き継いだ場合。

ドキュメントと実コードは乖離しており、問い合わせがあるとドキュメントより先にコードを開いてしまう。ドキュメントを開いても信用ならない、タメになる情報が書かれていない。

ドキュメントを直そうにも、誤り・足りないものが多く直しきれない。そもそものドキュメントのフォーマットが悪く、フロントエンドの処理とバックエンドの処理が一箇所に混在して記述されていたり、外部設計と内部設計がぐちゃぐちゃに混ざっていて抜け漏れが多かったり。

保守・開発者のためにもならず、当然顧客のためにもなっていない。

それでいてそんな現状を理解していながら、ドキュメントを作り直す工数を上長はよこさず。工数を与えていないということは「その仕事はしてはいけない」になるので、勝手に直そうとしていると止めろと注意される。それなのに「ダメなところはなんとかせい」とだけ言い残して去っていく。

開発時は必要だったのだろうか

さて、これらの資料、一から開発する時は必要だったのだろうか。それも怪しい。

「テーブル定義 : 1人日」「○○画面の処理定義 : 2人日」など、共通設計がないまま適当に画面単位で担当割りをされ、書かされることになった文書を書くには、先に実装が終わっていないと書けないことが多い。というか、その文書を書こうとする間に実装すればそれだけで事足りるような詳細度で、結局は裏でこっそり実装を済ませてからそれを日本語訳して提出したりしている。

何でこんな文書が必要なのか上長に聞いても、「実装より前に設計するのが普通だから」という、未だにウォーターフォール・モデルを盲信している日本の SE の典型的な根拠のない回答しか返ってこない。では、顧客に提出する文書なのかというと、顧客は「画面サンプルしか要らない」というので、顧客も必要としていない文書だ。ただし、顧客は「設計書の作成状況はどうだ?」と常に聞いてくる。読みもしないのに。

サラッと書いたけど「共通設計がない」というのは、共通設計という概念自体がまずないらしく、業務を整理する工程も取られていない。UML は誰も読み書きできない。

その資料、必要な人がいないのでは?

開発時も裏では実装が終わったところから書いていて、顧客は処理定義書なんて読まなくて、保守段階もメンテナンスする工数がもらえないので修正がなされず、段々とコードだけ変わっていので保守担当者は読まなくなる。上長はこれまでの開発工程の形式から必要な成果物の一種として書けと命令しているが、上長がそれでシステムや開発工程をできているわけではなく、UML も知らない程度の設計知識しかなく、当然コードも読み書きできないので、フォントサイズが揃っているかどうかぐらいしか見ていなかったりする。

結局のところ、そんな設計書、現場では誰も必要としていない。

それでも作らされる理由

会社の上の方の人間が、「現場の詳しいことや最近の技術のことを知るつもりはないが、これまでどおりウォーターフォールモデルとやらに沿って仕事をするなら、こういう設計書が出て来るはずだろう、その数字を報告しろ」とだけ言い残して丸投げするからだろう。

そんなもの作っても無駄でしかないですよ、と説明しても、詳しいこと・新しいことは知る気がない連中なので、いつまでも古いやり方が変わらない。

昔はウォーターフォール・モデルに沿って設計書を書く必要があったのか?

多分、昔は設計書が先に必要だったのだと思う。極端な話、パソコンを使わない場面では、先に設計書を作り、設計書どおり寸分違わずにモノを作ることが求められたと思う。建築などはモロにそうだろう。

システム開発にしても、コンピュータがまだパンチカードで動いていた頃、パソコンが非力だった頃は、可能な限り紙の上で設計をしておいて、1回打ち込んだら完璧なモノが出来上がる状態にまでしておかないと、コンピュータの実行コストがかかって仕方なかったのだろう。

しかし、それも20世紀までの話。今はコンパイルもサクサク行えるし、エディタは進化していて爆速開発できる。繰り返しコンパイルして自動テストをして、ということがやりやすい。だからこそ、「先にこういう動きをするはず、というテストを書いておいて、それからコーディングしましょう」というテスト・ファーストな考え方ができてきたのだと思う。

ドキュメントが全て要らないワケではない

さて、テストファーストとはいえ、「何を実装しようか」という話ができていないと、チームでのシステム開発はできない。

何を作るか、という話は、要件定義であり、それがまとまると「概要設計書」が出来上がるわけだ。ここまでは変わらず必要だと思う。

ただ、この間にある「業務の整理」が下手糞で、ココで UML 等を使った概念化をしていないことが日本の SE はほとんど。誰のどんな業務を、どういう風に改善するのか、という目的を明らかにできていないまま、何やら概要設計書の体裁をまとった意味不明な文書が出来上がっているのだ。

また、そこから先、扱う概念をどういうデータの形式にしていくか、というモデル設計や、データの受け渡し方やコーディング規約などを決める共通設計がされていない場合がほとんどだ。ココの設計・設計書が欠けているのにその先の詳細だけ考えても、方式がバラついて仕方ない。

あとは画面周りに関してはワイヤーフレームとモックアップがあるべきだと思うが、日本の SE はフロントエンドを軽視しているので、理解しようともしないまま「自分がよく知らないものは採用しない」と決めつけて成果物の中に入れない。だから、日本の SE が作るシステムはフロントエンドでのバグが多い。特に JavaScript の言語仕様を Java と同じようなものだと勘違いして起こすバグがとんでもなく多い。

ここから先は、実装とほとんど変わらないものになってくると思うので、コードとドキュメンテーションコメントで管理すれば良い。ドキュメンテーションコメントだけでは分かりにくい、という場合は、業務の整理ができていなくて、ユースケース図やシーケンス図が足りていない場合だと思う。

悪いのは誰だ?

ここまでの登場人物、みんなそれぞれに悪いところがある。

こういう思想を止めたら無駄な設計書は作られなくなる

結局のところ、技術力がない人間が技術屋のフリできてるのが日本の SE で、そのフリをするためにコードの日本語訳みたいな資料を部下に作らせて、何かあったらそれを読み上げることで難をしのごうとしているんだ。専門職に専門知識を持たない無能がわんさかいることが、Excel 方眼紙に繋がっている。