Murga

個人的に言いたいコト・主張・気持ち。

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

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

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

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

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

自分の基本主張

  • コードファースト。ソフトウェアは実際に動いているコードが主たる成果物であり納品物。設計書はオマケ。
  • コード中に書く、ドキュメンテーションコメントで補えるものは設計書を作らない。
  • 設計書を書くなら、コードへの変換ができるとか、コードとの同期が取れるとか、なるべくコードに近いものにしたい。
  • 設計書の内容に合わせて、作成に使うアプリケーションは積極的に変えたい。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

それでも作らされる理由

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

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

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

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

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

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

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

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

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

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

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

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

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

悪いのは誰だ?

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

  • プロジェクトマネージャー以上の管理者
    • なんとなく管理している気になりたいがためだけに、適当に数字化しやすいものを部下にやらせている。これが無駄。
    • その開発プロジェクトの目的が何で、その状態になっていることが分かる指標値を最初に考えれば良い。毎回同じ名前の設計書ができるはずがない。
  • システム開発を軽視している顧客
    • 読まない設計書を、書いているかどうかだけは確認する、無意味なことをしない。
    • 何を作って欲しいのか、要件定義はそちらが主体で行うこと。システム化方針はこちらが真剣に考えるので、「システム化できること」「システム化できないこと = するとまずそうなこと」を分別できる知能を持つこと。
  • 作らされている設計書に疑問を持たない担当者
    • 誰の・何のために作っているのかも分からないまま、言われたままに書いているヤツ。疑って声を上げる人間がいないからおかしなことがまかり通る。
    • 目的意識がないから出来上がるものは余計に支離滅裂。書くならせめてまともな日本語で書いて。
  • 問題提起と説得が仕切れない僕
    • おかしいと思ってることをうまく伝えられていない。相手を説得しきれていない。
    • 「この会社の体質だから治すのは無理だな」と諦めて、不要な資料と分かりながら作ってしまっている。

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

  • 「今までやってきたことを繰り返せばいい」という考え方。今まで炎上案件しか繰り返してきてないのに、改善方法を考えたりしない。
  • 形式を守ることが何より大事という考え方。順番どおりに・決まった形式のものを作ればいいと信じている。
  • 概念や哲学を考えようとしないこと。「システム屋なんだからそういう漠然とした話ではなくて詳細な設計を…」などと言いがちだが、漠然とさせたままにしないのが概念モデル化であり、流動的な環境の中で秩序を保つ術を考えるのがソフトウェア哲学だと思う。概念的・抽象的な考え方が出来ていないというのは詳細な話もできない状態だ。
  • コードや英語に対する拒絶反応を持つ人間がシステムを作ろうとしていること。恥ずかしいので「コードとか分かんないから (ヘラヘラ」みたいなの止めたほうがいい。それただの無能じゃん帰れよ。
  • それでいて日本語も不自由だから設計書も読み書きできていないが、母国語だからという理由だけで読み書きできた気になっていること。
  • 難しいことを簡潔に説明できる人間を欲しがること。複雑なものを複雑なまま理解する知性がないのであれば、こういう仕事に関わらないでほしい。

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

あなたはまだそんな「仕様書」を書いているんですか?

あなたはまだそんな「仕様書」を書いているんですか?