設計の理論

工学では現状、「設計図とは何か？」といった理論は存在しません。情報工学でも、「IT企業の仕様書をどう書くか？」という書籍は、ほとんどありません。大学生向けの情報工学の参考書でも、まず触れられてない分野です。

本ページでは現状では参照していない文献ですが（2022年2月11日）、設計の理論を紹介していると思われる関連文献として『岩波講座 現代工学の基礎』があります。ある程度、設計についての抽象的な説明があるかもしれません（たとえば『岩波講座 現代工学の基礎〈1〉設計の方法論』（2000/5/10）あたり）。 しかし岩波のこの本はそんなに厚くないし、ソフトウェアも含めては説明していなかったかもしれません（手元にないので確認できません）。

ITの場合、ビルド手順の記録が必要

集団でソフトウェアを作るとき、そのソフトウェアのビルド方法を仕様書に書かないといけません。（これは製造業の設計図などには無い、IT業界の独自の事情です。）

ビルドとは、実行ファイルを作ることです。

Visual Studio などのソフトウェア開発環境ツールは大抵、ビルド機能もあるので、最低限、作者が実際に使用した開発ツールを書いておく必要があります。ビルドに必要としたソフトウェア（ビルド実行ソフトや、必要なライブラリ）、ビルドのためのコマンドや操作手順なども、ひとつひとつ詳細に書くべきです。

実際に自分がそれらビルド手順のとおりにソフトウェアだけをインストールと設定を試してみて、もしその手順の指定に従えば（従うのが知識的に簡単かどうかはともかく）、とりあえずビルドできて、実行ファイルを生成できる程度には、書く必要があります。

ソースコード公開サイトなどのプログラムを見ると、説明書を見てもどこにもビルド方法や実行環境が書かれておらず、ビルドできずに使いようのないコードが時々あります。ビルド不可能ではあまり有意義なソースとは言えないでしょう。

必要な書類

一般のIT業界や製造業の場合、集団作業で必要となる書類は、主に下記のセットでしょう（編集者Sの推測）。

• 設計図（これは完成予想図である必要があります）
• 部品と機能の対応表（メンテナンス用です）
• 企画に至った経緯を記した書類
• 参考資料（外部メーカーの製品カタログなどは、その製品が販売中止する可能性があるので、会社の手元に製品の仕様表などを抜粋して残す必要有）

設計図とは完成図のことです。

さて、一般のIT企業や製造業では上記の設計図～参考資料に加え、必要に応じて「説明書」、などを加える場合もあります（業界や会社によっては、説明書は上記セットとは別の本棚などに分離する場合もある）。この4〜5点セットの書類を、集団作業の便宜のために、将来にわたって残していきます。（土建や製造業などの堅い業界の場合は、「設計図書」（せっけい としょ）、などの名前で管理されることもあります）

娯楽産業ではない一般のIT企業や製造業でも、製品の企画に至った経緯を記した書類を、大元のアイデアを考えた会社の側では残しています。（ただし一般企業の場合、社内プレゼン用資料の流用の場合もある）。上記セット一覧のうちの「設計図」はゲーム業界では「仕様書」に対応しており、「企画に至った経緯を示した書類」は「企画書」に対応しています。一般企業では書類の名前は、「企画書」ではない場合も多く、業界や会社によって異なります。

企画書だけでなく、マトモな科学論文とかでも、既存品と今回の製品とはどう違うのかという構成が好まれます。つまり、論文なら「何を新発見したのか？ → いままでの理論ではどうだったか？それと今回の新発見とでは何が違うか？ → 発見のプロセスや詳細など」といった構成が、マトモな科学論文のあるべき構成です。

また、メンテナンスのための図面として、「フロー図」とか「モジュール図」や「システム図」等、設計図としての目的でない将来的なメンテナンス改修などを見越して作成される図を、保存しておく必要があります。

一般IT業界の仕様書の書き方の本やwebサイトを見ると、「要件定義書」「内部設計書」「外部設計書」「ネットワーク図」「業務フロー図」「インターフェース設計書」「モジュール設計書」などの色々な書類・図面がありますが、発注元で最低限必要なのは上記4点セット（完成予想図、メンテ用資料、企画書類、外部資料）でしょう。IT業界特有の設計書類も、完成予想図またはメンテ用資料を作成するため手段に過ぎません。

マツダ自動車では図面で企画説明する

エンタメ業界ではないですが、自動車会社のマツダ自動車では、 新製品の構想などの規格を社長・会長に伝える際、 口頭や文字だけで伝えようとすると「図面もってこい」と、たしなめられるそうです。

別に企業秘密でもなんでもなく、東京ビッグサイトや幕張メッセなどで開催される「自動車部品生産展示会」みたいな感じの名前のイベントで、普通に2010年ごろマツダ社員が会社パンフレットなどでそう説明していたりしていました。

なおマツダの例ではないですが、製造業では企画に限らず、外注業者に対して一品モノの制作作業の指示書や実験の指示書などを書く際にも、 パワーポイントなどで簡易的な絵を作って、外注したい動作を説明することもあります。

なぜこうするかというと、絵にすることによって、文字の解釈ミスを防げるからです。

結局、アニメで言う「絵コンテ」やマンガでいう「ネーム」のような下書きの絵の手法は、エンタメ業界だけでなく、ほかのさまざまな業界の仕事でも企画や作業指示などでも応用が利くのです。（というか、だからこそか中学校の美術や国語などでも「絵コンテ」が検定教科書で紹介されているのでしょう。あらためて、義務教育の教科書はとても考え込まれて著作されていることに気づかされます。税金パワーは凄まじいです。）

「設計図」とは完成図である

では「設計図」とは何かというと、製造業の場合での「設計図」の意味を説明すると、それは「完成予想図」です。「完成予想図」というところがポイントで、実は生産方法などは指定していないのです。なので設計図だけでは、実は何も生産できないのです。

なので設計図に加えて、現場で必要な生産方法の技術をもった技術者が、さらに必要です。なので、設計図はあくまで、最低限必要な情報でしかないのです。実際には、設計図以外にも、生産方法についてのさまざまな情報が必要です。

ですが、どこの業界でも、生産方法については図面化しないか、たとえノウハウを部分的に文書化していても社外秘にしていて非公表なのが通常です。

IT業界でも、あるソフト製品のプログラミングの具体的なノウハウについては、その製品の「仕様書」には記載されないのが通常です。

完成予想図として「部品図として、このような寸法（各部の長さ）・形状・材料をもった部品を図面の指定どおりに作れば、あとは組立図に部品どうしの相互位置が書いてあるので、（組立図の）その位置指定とおりに取り付ければ、必ず完成しますよ」

という状態にまで、部品図と組立図の状態をそれぞれ完成予想図の形で書き上げていくのが、図面を書くという事です。

技術的の企業でいう「設計図」の意味は、おおむね、こういう意味です。

完成図は、実装の手段とは区別しなければなりません。

基本的に、実装時の手段は提示しないのが安全です。なぜなら、多重下請けや大人数などで開発をする場合、事情を知らない相手もいるので、いつのまにか伝言ゲーム的に、完成品への要求事項のなかに、単なる手段の一例とが混ざる可能性があるからです。ともかく、要求事項と手段は、混ぜてはいけません。

よかれと思って、実装の手段の一例を例示してしまうと、それが下請けなどの際に、伝言ゲーム的にいつのまにか間違って要求事項として混ざっていく可能性があります。

そういった先も見越して、設計図を書く必要があります。

どうしても実装の手段の一例を伝える必要がある場合は、それが一例であるのにすぎないことを確実に伝わりつづけるように、なんらかの工夫が必要になります。

設計図はチェックリストを兼ねる

もし、納品される品物が仕様を満たしてない場合、けっして合格品としてはいけず（つまり「検収」してはいけず）、（発注者は）協力会社に作り直しを要求します。この仕様違反のさいの作り直し要求はIT業界にかぎらず製造業でもどこでも、受け入れ検査は通常、そういう仕組みです。

ソフトウェアを作る場合も、最終的に製品の完成の段階では、最低限このような水準にまで、設計図を作りこんでいきましょう。（ただし、ソフトウェアには「寸法」など形状の条件は無いので、そこはアルゴリズム的な条件に意味を読み替えること。）

そもそも仕様が確定していないと、品質の検査のさいの検査基準そのものが無い状態なので、品質の高い・低いすらも測定できなくなってしまいます。品質管理の前提として、仕様の確定が必要です。

製造業では図面をもとに見積もりをします。基本的に技術系の業界では、設計図をもとに見積もりが行われるます。

学生は企業社会を知らないと思うので説明しますが、コンピュータ業界にかぎらず、そもそも製造業なども含む技術系の業界で、設計から生産までの流れがどういう工程で行われているか、説明します。

設計図では生産方法を指示しない

まず、なにかの設計図では、具体的な生産方法は指示しません。たとえば、組み立てた後の形状がどうなってるかは組立図（くみたてず）に描いても、しかし、「どうやれば組み立てられるか？」とかの情報は一切、そういう事については『設計図』では指示しません。

ともかく、なにかの設計図は通常、その製品の完成図である必要があります。製造業で「図面」と呼ばれているものは、こういった具体的な完成予想図のことです。

そして、その完成図はいくつもの部品から成り立っているのが普通なので、完成品をいくつかモジュールごとに分解した部品図（ぶひんず）をいくつも作成して、それぞれの作成担当の作業者に渡します。

こうすることで、分業もしやすくなり、一石二鳥です。

あいまいさを無くすのが設計図

基本としては、設計図とは、設計図だけを見ても、あいまいさの無い状態で完成品の満たすべき具体的な条件が分かるようにしなければなりません。

さて、製造業などでも、「図面」という完成予想図があります。

よく、IT業界でいう「現場で見つかった仕様書の不具合を仕様書にフィードバックする」とか言う表現は、おそらく完成予想図のような書類のことを指していると思います。

なぜなら製造業でもフィードバックは図面に対して行います。なので、製造中に不具合が見つかれば、どんどんと図面が改訂されてゆくし、そのために設計者は現場に立ち会うし、場合によっては設計者みずからが製造もしていきます。

技術系の業界では一般に、書類で作業指示を出すときに、いちいち、けっして具体的に、「作業員であるアナタは、○○のコンピュータの△△ボタンを押して、××をしてください」のような指示は出さないです。

指示はそう出すのではなく、図面のような完成予想図（ただし決定稿）を出して、「この完成予想図のとおりになるように作っておいてください。」というような指示が出ます。

横断的な説明をしたい場合

さて、IT業界の場合、末端の部品プログラム完成予想図を描く前に、普通の設計では既にフローチャート図または状態遷移図などといった、全体的なシステムの図面を書くのが望ましいとされています。（以降の説明では、言い回しの省略のため、フローチャート図または状態遷移図を単に『フロー図』または『フローチャート図』と略記する。）

なので、もし横断的な説明をしたければ、このフローチャート図を作るとき、このフローチャート側に説明を追加するとか、あるいは、フローチャート図を参照する形で別途の参考図を追加するとかすれば、良いかもしれません。

こうすれば、もし末端部品プログラムを訂正することになっても、訂正の必要のある図面は、末端プログラム図面と、その直接の上流のフロー図あるいはフロー別途参考図だけのたった2枚に限定できますので、訂正の手間を減らせるので効率的です。

なお、もしかしたらIT業界でも、状態遷移図やフローチャートを描かないで設計する事態も企業によっては横行しているかもしれませんが（原理的には、状態遷移図やフローチャート図が無くても、エクセルなどで作成した部品プログラム仕様とその組み立て仕様のエクセル形式の完成予想図だけでも、原理的にはソフト設計できてしまう）、しかし、こういう状態遷移図などの画像での説明を省いた設計では設計ミスが発生しやすく、結局、再設計などの手間が掛かってしまうのがオチです。

一枚の図面の中では内容重複はオッケー

なお、一枚の仕様書の中では、内容の重複はオッケーです。

たとえば、機能の似たモノを2個つくるとき、

2個目の説明では、「○○については△△と同じ」のように、「～～～と同じ」というふうに説明できるから、です。製造業でも、一枚の図面に正面図と側面図の2方向の図のある場合、側面図に参照値として正面図の値を書くと、正面図の設計変更にともない、ときどき側面図にある参照値を修正し忘れるミスがあります。）

なので、よほど仕組みの複雑な難しい製品でないかぎり、なるべく2回目以降の説明では具体的内容は書かないのでおくのが、設計の図面では修正モレを防げるので安全です。

ただし、これはあくまで、設計図面の書き方です。教本や指導書などの書き方とは、設計図面の書き方は、違います。もし、新人むけの指導書や教科書・教本を書く場合には、やや重複のある内容でも何度も説明して覚えさせましょう。

要求事項書

要求事項は、「○○してもらいたい」という指定も必要ですが、ソレとは別に、できれば、「なんの目的で、そういう指定をしているか？」などの理由も書いてあると、ニュアンスが正確に伝わるので、伝達ミスなども減ります。

企業秘密などで無いかぎり、できるだけ、目的も平気したほうが良いでしょう。

要求事項の書類には、要求には理由も併記するのが望ましいと指導されているようです。

さて、一般IT企業で要求事項書の話題に戻るとして、また、意外と伝達側が設計ミスをする場合もあるので、目的も書面で伝えておくことにより、相手先の人が、気を聞かして検証してくれます（べつにボランティアで検証してくれるわけではなく、どっちみち相手先が設計中に結果的に検証することになるで、だったら要求事項に目的も書いておいたほうが効率的になる）。

なんども指摘するが、「要求事項」だの「設計図」だの何種類も作る書類セットの書き方では、説明が重なって多いぶんには問題ないのです。（ただし、要点などを抜き出した簡略版の説明も必要。）

大は小を兼ねます。

なお、社会人の情報伝達では、結論を先に言うのがマナーなので（詳しくは『中学校国語/現代文/報告書の書き方』）、要求を先に伝えてから、理由を直後に伝えます。つまり、文章のテンプレートとしては、

[要求]
[理由]

のような順番になります。

設計図の各書類は一般的に外部には非公開なので、書類セットくらいでしか体系的な説明をできないので、むしろ別書類にて説明の重複などがあって相互検証できるくらいのほうが、安全なのです。なお、要求事項の段階では、あまり細かく事項書を作りすぎずに、そのぶん実際のプログラムの開発を早めましょう。

データ台帳

重要なことは、一般のソフトウェア開発などでの実務では、なんらかの特殊な数値データが組み込まれている場合、台帳と実物プログラムとによってダブルチェックをするという事です。（ゲームだけでなく、製造業の組み込みソフト開発などでも、台帳などによってダブルチェックをしています。）

IT業界では、ダブルチェックを軽視している人が多いですが（たとえば電卓とパソコンソフトとの計算結果のダブルチェックを批判する言説がネットに多い）、そういうのは製造業や組み込み業界などでの実務を知らない知ったかぶりのタワゴトなので無視しましょう。

マトモな業界では、プログラムの検証のため、そのソフト以外およびそのソフトを動かしているハードウェアとは別のデバイス（電卓でも良い）を使って、ダブルチェックをするのが常識です。（※この常識には出典を出せませんが（企業秘密などに関わるので）、しかしダブルチェックを軽視する側の主張も満足な出典を出せていないので、対抗的にこの文を残します。）

さて、入力されたハズのデータの台帳のような内容の一覧の書類が、一般の技術系企業では必要です。業界で「台帳」と言うのかは知りません。名前が無いと困るので、とりあえず土木工学ではこういうのを「○○台帳」というので、それに習って「データ台帳」という題名を本セクションでは、つけているだけです。なので、IT企業では別の呼び名かもしれません。

多項式近似

測定値などで、入力変数が一変数なら、エクセルなどを用いて多項式近似が出来ます。

一般にIT業界での実務の多項式近似では、原理的には9次でも20次でも、どんなに次数が高くても（おそらく int 整数型の限界くらいまで）計算できてしまいますが、

しかしIT業界などの実務では人間の検算などの手間を減らすために、なるべく、せいぜい2次式や3次式といった、低めの次数におさえて利用するのが、IT企業では普通です。

もし先端科学のための多項式近似なら、9次を超えるような多項式近似をするような場合もありますが、しかし、一般の企業では、そこまでの多項式近似は不要ですし、むしろ検算などの管理の手間が増えるので、9次のような多すぎる次数は嫌われますので、なるべく2次ていどに抑えましょう。

バグあると人の死ぬ業界

ゲームではバグがあっても、人は死にません（過労自殺などを除けば）。なので、アイデアが思いついたら、どんどんとプロトタイプで試してみましょう。

ですが、他の業界だと、バグがあると人が死ぬ場合もあります。たとえば、製造業での、組み込み機器などがそうです。

書籍で紹介されている事例だと『メタルカラーの時代』シリーズ（山根一眞（やまね かずま）による取材）で、 「日本ユニシス」というIT企業がかつて、提携している別企業のNC工作機械に向けた組み込みソフトの開発で（組み込みソフト部分をユニシスが開発）、開発テスト中のバグにより工作機械の刃物が本体にぶつかって折れて飛んできて、あやうく人が死ぬところだった、 ・・・という感じの事例がインタビュー先のプログラマから紹介されています。 それまで日本ユニシスおよびその担当プログラマーでは、組み込みの仕事はほとんど扱わずに、どちらかというとIT業界内での顧客を仕事をしていたので、そういう人が死にそうな事例に経験することがなかったので、製造業の組み込みソフトでは特にバグおよびバグ予防に対する考えをIT業界内の仕事とは変えなければならない必要があることに気づかされた、とユニシスの技術者はインタビューで述懐しています。

履歴の管理

一般のIT企業でいう仕事の「仕様書」では、開発前の段階で書いた要件定義書や設計図（完成予想図）やコード解説書など」を、ソフト完成後にも残す必要があります。

なぜなら、開発前～開発中の経緯を、上司や他部署に事後的に報告したり、のちに入社してくる後輩などに教育としてソフト開発時の出来事を教えるためです。

このため、こういった仕事の書類には、著者や、著作・改訂の日時（「改訂日: 2018年8月30日」）や改訂者（「改訂者: 山田太郎」）などの履歴（りれき）も記載する必要もあります。

版	年月日	作業者	編集内容の要約
第1版	2018年7月10日	鈴木花子	著者
第2版	2018年8月30	山田太郎	改訂

のようになります。（企業では、こういうページのパソコンでの文書管理は、エクセルなどの表形式データになってるのが普通。）

さらに改訂の際には、それぞれの版の改訂内容の要約を書く必要すら、あります。

アマチュアの場合なら、『メモ帳』アプリなどで説明する場合もあるかもしれないので、たとえば

第2版, 改訂日: 2018年8月30 , 改訂者: 山田太郎

第1版, 著作日: 2018年7月10日, 著者: 鈴木花子

のようにアレンジする必要があるかもしれません。

アマチュアのゲーム製作の場合、エクセルまでは不要でしょう。

ファイル名の冒頭番号

ゲームを例に説明します。

ゲーム産業に限ったことではないのですが、企業でのパソコン内での、ファイル名やフォルダ名の管理手法として、たとえば何かの説明書きのファイルがいくつもある場合、

01_キャラクター設定
02_モンスター設定

などのように番号順をつけて命名することもあります。「01_キャラクター設定」でひとつのフォルダ名です。なぜこのように番号を冒頭につけるかというと、もしパソコン上で名前順に並び替えたときに、必ず狙った順番どおりにさせるためです。

そして、たとえば「キャラクター設定」フォルダ内に、さらに

000_ゴンザレス設定.doc
001_アルベルト設定.doc
002_エドモンド設定.doc

のように、さらに　番号づけの設定があることもあります。

たとえば、「ゴンザレス」というキャラが主人公のゲームの場合、彼が最初に来てもらわないと困るわけです。もし番号が冒頭に無いと、「ゴンザレス」よりも「アルベルト」のほうが五十音順では先に来てしまいます。

しかし、上記のように番号を冒頭につける方式を採用することで、あとでどんな名前の新キャラクターを追加しようが、必ずファイル検索の名前順検索では「ゴンザレス」が最初に来るようになるのです。

なお、業務用のファイルでは一般的に、冒頭番号と項目名とが別々のものであることを強調するために、半角スペースを使わずにアンダーバー「_」を使うのが一般的です。

観察力があるかないか次第（しだい）

音楽CDでも、Windows media player を使って昔の1990年代の古いCDをmusicフォルダに取り込むと、

01 トラック1.wma
02 トラック2.wma
03 トラック3.wma

などと保管ファイルが自動的に出来上がったりするわけです。「01 トラック1」でひとつのファイル名です。

Windowsの接続先サーバがもし曲名を認識できれば、 たとえばもし取り込んだCDがアニメ『新世紀エヴァンゲリオン』TV版のサントラCD『Neon Genesis Evangelion, Vol. 3』なら、

01 幸せは罪の匂い.wma
02 無限抱擁.wma
03 Normal Blood.wma

などと曲名の入った保管ファイルが出来上がったりするわけです。この例の場合「01 幸せは罪の匂い」でひとつのファイル名です。

こういうふうに観察力さえあれば、色々なことから技術を勉強できます。最近はもう販売されるCDにコピーガードがあるので、PC取り込み可能かどうか分かりませんが。

なお、CD本体のほうは、windowsのファイルエクスプローラーで閲覧すれば、

Track01.cda
Track02.cda
Track03.cda

のようにトラック情報だけが記録されています。

IT企業に限らず製造業でも、たとえば図面ファイルでは

01_構想図
02_外観図
03_部品表
04_部品図

などと、冒頭番号ごと名前をつけてフォルダ管理するのが一般的です。

フリーソフトのファイル構成などでも、本ページはゲーム教科書なのでゲームに置き換えて説明しますが、

01_Read me.txt
02_使用素材.txt
03_更新履歴.txt
Game.exe

のようなファイル構成のフリーソフトも時々、見かけます。

説明書

操作テストをしながら書く

フリーゲームなどは、あまり説明書が細かくかかれないので、気にする必要はないでしょうが、一般IT企業のソフトウェア説明書や製造業の組み込みソフトなどは、もっと細かく一通りの操作方法を説明します。

イメージしやすさの都合で本ページでは、製造業などの組み込みソフトを例に、説明書の書き方を説明します。

なんと、組み込みソフトの説明書を書くためには、操作テストが必要です。

だから例えば工場の生産ライン用の設備に組み込まれてる組み込みソフトの説明書なら、その説明書の文面は、工場で下書きしてるわけです。

オフィスで下書きするのではなく、工場で下書きするのです。なので、工場にノートブック（文房具）と筆記用具（要・赤ペン）を持ち込んで、そこで説明書の文面を下書きするわけです。

たいていの新人は、実機での操作テストに気が引けがちです。

実機で操作テストばかりしてると「周囲の先輩から『この新人は書類も読まずに実機をいじって遊んでる』と周囲に見られるんじゃないか？」と不安になったりとかして、実機によるテストを遠慮しがちです。また、仕様書は読んでて勉強になりますので、ついつい仕様書ばかり読みがちで、テストを遠慮しがちです。

しかし、それは新人特有のよくある勘違いなのです。説明書を書く場合にも、実機でテストプレイをするべきなのです。

なので、下書きが終わったら、さっさと実機テストをするべきなのです。

組み込みソフトの場合の手順

まず、仕様書などをもとに、説明書の大まかな章や節などの構成を、仮決めします。

大まかなページ数などの仮決めのために、仕方なく仕様書を見ながら、仕様書から想定されるハズの操作方法を書きます。

この下書きは、これはこれで必要であり、あとの操作テスト時にチェックすべき項目を示したチェックリスト的な意味合いもあるので、とりあえず、実機プレイなしですが下書きをします。

ですが、この想定した操作方法は、まだ何のテストもしてないので、高確率でミスが含まれています。

なので、下書きした説明書のプロトタイプと筆記用具（赤ペン）を持ちながら、実機のある現場に移動して、到着したら実機で説明書どおりにテストプレイしながら（絶対に説明書を見ながら、杓子定規に説明書どおりにプレイします）、実機操作中に発見した説明書のミスを、赤ペンで下書き説明書に、追記でメモ書きしていくワケです。

このように仕様書ばかり読んでないで、さっさとテストします。

だから、説明書を書くオフィスは、そういうテストが気軽にできる環境の近くに存在する必要があります。

また、組み込みソフトの説明書を書く技術者は、工場の組み込みソフトを書くなら、技術書の服装としてはブルーカラーの作業着で仕事してるわけです（背広ではないです）。作業着でないと原則、現場に入れないので

組み込みソフトは、機械などに組み込まれてるわけですから、安全が確保されていて可能な限り、仮想化などではなく、実機でテストします。 （仮想化でテストすると二度手間になります。なので可能なら最初から実機でテストしたほうが早いです。）

このような仕事を、よく新人がやらされます。

新人は消費者目線に近いので、どこの業界でも、新人がよくテスターにさせられることが多いのです。

同様の理由（消費者目線）で、説明書を書く仕事も、どこの業界でも、新人がよく説明書を書かされます。

子供向け商品など

子供向けの玩具で電子玩具の説明書などだと、場合によっては説明書の文面が子供口調（「～だよっ！」とか「～だね！」みたいな口調）で説明が書かれていたりしますが、けっして説明書を書くお仕事が子供の学校の図工みたいな作り方をしてるワケではないでしょうし、おそらくは実際の執筆手順は上記の組み込みソフトの説明書のような感じの手順で説明書を書いていってると思われます。説明書の口調という表面にダマされないようにしましょう。

ああいう子供口調やら女口調の説明書は、集団作業の場合なら、下書きの段階での口調は、普通のビジネスマン的な書類の口調で書いているか、たとえ　くだけた下書きの場合でも普通の大人のくだけた口調で下書きを書いているのであって、あとの工程で口調だけ入れ替えて子供口調や女口調に入れ替えるという手間を掛けていると思われます。けっしてイキナリ、子供口調とかで書類を書きはじめるわけではありません。

失敗学

失敗学

失敗は無数にパターンがあるので、すべての失敗を学ぶことはできません。 しかし、初心者がよくある失敗パターンというのは割と限られています。

そういうのは、学ぶようにしましょう。

航空事故など大規模事故が起きた際に組織される『事故調査委員会』も、失敗を次世代に繰り返させないために、原因究明をして事故調査をしているわけです。

高校物理などで習う「共振」現象だって、その共振によって米国のタコマ橋が実際に崩壊する事故という失敗例があったから、 その失敗例に学ぶことで橋梁（きょうりょう）設計の理論が進歩したののですや。

なお、畑村は、2011年の福島原発事故の際、国家の組織する原発事故調査委員会のリーダーを勤めています。

チームにおいて失敗が起きた場合は、人的ミスではなく、組織設計のミスだと見るべきです。畑村はそう提唱しており、だから原発事故調査でも、責任追及をしないこと・させないことを貫きました。

パラメータ調整の理論

手法

アブストラクト

「目標はすべて実現しようとするのではなく、優先度の差をつけ」、「機能てんこもり家電だと商品コンセプトが消費者に分かりづらいから、消費者に商品の魅力が伝わらない。だからもっと機能を絞るとかして、分かりやすく」する方が良いでしょう。

パラメータ・バリエーション

背景となる工学的な考えかたとして、下記の「パラメータ・バリエーション」という考えかたがあります。「パラメータ・バリエーション」とは何かと言うと、複数の変数からなる多変数関数のようなモノの適正値を探すときに、とりあえず1種類の変数だけを実験的にイジッてみて、その後に測定してみることで調整していく方法です。フレデリック・テイラーという機械工学者が、工作機械の研究での旋盤加工の回転速度・送り速度・直径・角度などの他変数の最適条件を探す研究の際に、こういう探求手法を1880年ごろに提案しました。

ただし、あくまでテイラーのこの手法そのものは、研究の方法でしかなく、つまり活用可能なのは大企業の工場のような十分な予算と研究員のいる場所でのビッグビジネス的な企業での科学研究的な方法なので、中小零細の企業での設計の実務では、そのままでは合わない方法かもしれないので、私たちは適宜、自分の勤務先の状況に応じて「パラメータ・バリエーション」をアレンジして応用する必要があるのでしょう。

歴史的には、パラメータ・バリエーションの考え方のほうが古く、ストリンガー経営哲学やゲーム調整方法よりも古いですが、しかし歴史の順番どおりに学ぶ必要はないです。学習はたいてい、現代の実務的な方法から学んでいくほうが効率的です。

もし数学の用語に読者が詳しいなら、「パラメータ・バリエーション」とは、実験による検証において「偏微分」（へんびぶん）や「変数分離法」を合わせたような、謎（なぞ）の調整手法を、解を求める代わりに擬似的に実験で用いたモノという表現でしょうか。

ちなみに物理学の解析力学という分野にある「変分法」（へんぶんほう）という計算手法を英語でバリエーションというが、しかし、ギルブレスのいう「パラメータ・バリエーション」は明らかに（物理学の）変分法とは別の手法である。

たとえば機械設計の業界で昔から言われている教訓として（なるべく新規設計では）「材料と構造を同時に変えるな」というのがあり、日経クロステックのwebサイトでもそう紹介されています。引用元の日経クロステックの記事では「2つ以上のものを同時に変更するときは、組み合わせによる問題が起こりやすいことを示唆している」と指摘されています。

自動車業界だけではありません。航空機業界でもそうです。

三菱航空機が国産航空機 MRJ に開発失敗した原因のひとつが、このミスです。採用事例のまだ蓄積していない最新技術を根本の仕様としていくつも導入してしまい、それを機体の基幹部品にしてしまったために、アメリカでの安全性の証明が取れずに、最終的に事業撤退になりました。

にもかかわらず、経産省が相変わらず、オールジャパンで国産旅客機の開発を再開しようとしており、ロードマップにて、複数の新技術を入れようとしています。水素利用とか、グリーンイノベーションとか。

日本だけでなく、韓国の兵器開発なんかも、似たような、普通の設計が出来ないのに、先端的な技術ばかりを導入しようとして、いつも頓挫します。いまや、一部の分野では北朝鮮にすら抜かれています。

医学の世界では『標準医療』といって、普通に普及している治療技術こそ、実は世界中で検証されている、費用対効果のもっとも優れた治療法だと考えられています。医学書で、医学書院（出版社名）が『標準生理学』とか『標準薬理学』とか出していますが、そういう意味合いです。

動点固定法

悩みは個別に切り分けるのが解決の基本テクニック

例えば、「僕はクラスのA子が美人だと思うのですが、でもA子は特に僕に気がないようで、それどころかA子は僕をいじめるときもあるし、僕は成績も普通でスポーツの成績はあまりよくなく、進路は○○を目指していますが（以下略）」という悩みがある場合、問題を切り離して、解決しやすい問題から解決していけ。

まず、A子がときどきお前をいじめてくる問題については、他の問題と切り離して考えろ。これは他の問題と切り離しやすいから。進路やそのための学力も、他の問題と切り離せる。お前の受験勉強で解決できるからだ。

そして、そういう問題の切り離しをした上で、美人のA子が好きでいるべきかどうかという問題については、まず他の問題と切り離して、これだけ考えろ。 いじめてくるA子なんて忘れるもよし。どうしても美人の忘れたくなくて未練が強く残るなら、イジメの復讐としてレイプするとか、いろいろと行動の選択肢がある。

「困難は分割せよ」

「仕事がうまくいかないときは、この言葉を思い出してください。『困難は分割せよ。』あせってはなりません。問題を細かく割って、一つ一つ地道に片づけていくのです。この言葉を忘れないでください。」

この考え方を大人向けのビジネスや設計にアレンジしましょう。具体的な手順としては、まず、

1. 箇条書きなどを用いて、問題をそれぞれ解決可能なレベルにまで分割して書き出すことで、問題の要素分解および「見える化」をします。
2. また、問題を分解したことで、とくに解決したい問題は優先的に解決するなど、優先順位をつける事も出来るので、その後は効率的に作業できます。
3. そうすればあとは、優先順位の高い順のうち、解決可能な問題をひとつずつ解決・対応など具体的行動をしていけばいいのです。

このように箇条書きなどによる可視化をもちいて　して、問題や悩みを、これから自分のするべき行動の「計画表」に置き換えていくのです（つまり問題を「ToDoリスト」「やることリスト」などといったものに置き換える）。

たとえもし結果的に問題を解決しきれなくても、何もせずに放置した場合よりかは事態は遥かに好転しているでしょう。

数学的に不可能なことなど

小室直樹の「二値最適化」の問題

政治哲学などの格言で「最大多数の最大幸福」という言い回しがありますが（なおこの格言を『ベンサムの功利主義』という）、しかし京都大学の数学科出身の経済学者・政治学者の故・小室直樹の著書によると（経済評論の書を多く出している）、これは数学的にはありえないとの事です。

小室の言い回しは忘れましたが、たしか「二値最適化」のような表現で言うらしく、それは数学的に存在しえないことが証明されているとおことです。一般に、（二変数関数ではなく）二値以上の関数を同時に最適化するのは、数学的に不可能とのことです。なお、数学・工学では「変数」は入力のことです。一方、「値」は出力のほうです。

小室が言及したか覚えてないですが、二値最適化の例外があるなら、たまたま偶然に同じタイミングで複数の出力値が最大化する関数などの特殊な形状の関数でない限り、一般には二値最適化はありえないでしょう。

小室によると、そもそも「幸福」をどう数値化するのかという議論が昔からありますが、仮になんとか幸福を数値化できたと仮定しても、二値最適化は数学的には不可能とのことです。

数学的にありえるのは、「一定多数の最大幸福」または「最大多数の一定幸福」のみだと小室は著書で言います。

小室は三値以上については述べてませんが、たったの「二値」ですら同時に最適化するのは数学的にはありえないわけですから、ましてや三値の同時最適化はありえないのは明白でしょう。

小室は東大・京大・ハーバード大などを卒業して著書多数で先端の経済学・政治学・法学を学んで著書まで書く経済学者・政治学者ですから（ただし学位は法学博士）、もし三値最適化がありえるのなら、そういった大学の後輩の天才たちがとっくに議論して経済学書などに書かれるわけです。書かれてないのですから、推して（おして）知るべきです。

ただし「二値最適化がありえない」の前提として、人口集団の性質や規模の前提として、経済学で扱うような十分に人口が多くて経済規模も大きい集団を前提にしているでしょう。

小室は特に前提を語っていなかった気がしますが、上述の仮定のため数学的には連続関数（ほとんど途切れずに、つながっている関数）で滑らかな関数（ほとどの場所で微分可能な関数）を前提にしていると思われます。

パレート最適

一応、経済学では「パレート最適」という、複数の（出力値ではなく）入力変数の調整に対応する理論もあり、パレート最適はどういう手法かというと、「どうやら現状が最適でありそうだ」と思われる状態になったら試しに条件を部分的に少しだけ変えてみて、もし悪化したら、「変更前の状態こそが、現状の条件の近くででは最適っぽいようだ」とみなす手法です。

しかしこれは出力値ではなく入力変数だけ複数の場合の手法です。出力値そのものが複数個の場合については、「パレート最適」の理論は何も保証していません。

メンテナンス用の書類の概要

完成形をつくるだけの「設計図」的な「仕様書」だけでは、バグ発生時や設計ミス発生時などのさいの修理が不可能です。

また、ITソフトウェアなら、移植などの際に、もしソースコードだけしかなくて書類不足だと、「コードがどのように動いているのか？」を後任の人が把握できずに、移植困難になってしまうトラブルもあります。

前任者が会社を辞めてしまっている場合などもあるので、色々と書類が必要でしょう。こういうことから、もし下記のような資料が無いと、不具合の発生時に、修理のための設計変更で、どこをどうイジればいいか特定できず、困ります。

• 部品と機能の対応表（下記では「フロー図」、「コード解説書」などと呼称することもある）
• 「なぜ、こういう設計になったのか？」という設計者の思考の経緯を伝える資料

というか、残念ながらこういう資料の不足している職場は多く、なので日本のIT技術者は困っています。

上記書類のうち、特に「部品と機能の対応表」、「コード解説書」は、メンテナンス目的以外にも、設計図のチェックにも利用される。なので、そういう目的もあるので、ぜひ作成しておくのが望ましい。

「部品と機能の対応表」のことを、IT業界で何と言うのか、このページの著者は知りません。しかし、ともかくそういう対応表がないと、メンテナンスが後々に困難になります。

なぜ書くのか

発売後の（一般のIT企業では）ソフトにも、修理・メンテナンスが不可能になる場合があります。

そのため、製造業などの組み込みソフトなど、まともなIT業務では、ソースコードの内部構造・全体構造のコード解説書とでも言うべき書類があることが望ましいです。（特に名前は決まっていない。また、中小企業などでは作成しない場合もある）

一般のIT企業では「内部設計書」や「プログラム設計書」などの名前の場合もありますが、しかし既に設計図などで大まかな指定はできていますので、設計の時点では、これらの「設計書」が不要な場合も多くあります。

これらの書類の目的は、どちらかというと、設計よりも、後日に読み返したときのメモ書きです。主要な変数、主要な関数などは、第三者が、なんのドキュメントも無い状態でその意図を読み取るのは、なかなか手間が掛かります。なお、最終製品やあるいはコードだけから逆に設計書や設計図などを書き起こすことを「リバース・エンジニアリング」と言います。リバース・エンジニアリングは、本来なら、後任者などには、させるべきではないのです。

大目的として、完成後のメンテナンスなどの際に、リバース・エンジニアリングという手間のとても掛かる作業を、けっして後任者にしないでも済むように書類を残すのが、正しい書類作成および書類管理のありかたです。これが、前提の大目的です。これさえ押さえてくれれば、ほぼこのページで言いたいことは尽くされています。このページの残りの説明は、単にイメージを具体化するためのケーススタディです。

会社でリバース・エンジニアリングの手間の発生が起きるのは、経営者にとっても時間と予算のロスでしょう。また、リバース・エンジニアリングをさせられる側である社員も、利益を生み出すわけではない作業に時間を多く取られ、とても負担です。なのでとにかく、リバース・エンジニアリングの発生予防が必要です。

で、具体的にどうすればいいかというと、リバース・エンジニアリングの発生を防ぐためには、なんらかの方法で、少なくとも主要な変数や関数と、その設計意図の対応表のようなものが必要です。

（完成図である）設計図だけでは、このような機能の解説をするのは不可能または困難なので、さらに変数・関数と、設計意図との、対応表のようなものが必要です。この対応表のようなもののことを本wikiでは「コード解説書」と呼んでいます（IT業界で何と言うのか知りません）。（設計図だけでも機能の解説を出来ているなら、その部分は解説書に書く必要はありません。）

要するに、機能と部品との対応表も残すべきだという亊です。「この部品、どの機能に対応してるの？」ってのが分かればいいのです。

異業種の例ですが、下記の２つの回路の図面を見比べてください。

クロック入力付きRSフリップフロップ（NOR型）

フリップフロップをフロー図で表現した例

どう比べても、右の「フロー図」のほうが、仕組みが分かりやすいでしょう。もし回路設計の専門外の素人が上記の回路図面を見ても、フロー図のほうなら機能が一目瞭然です。

このように、部品と機能を比べる書類があれば、とても後任者がラクになります。

また、このような部品と機能の対応の書類を作っておくことで、設計ミスの防止にもつながります。

上記の図面の例は、電気回路の設計の業界のハナシなので、ITではないですが、ともかく、こういう部品と機能の対応表があると、仕事がいいカンジです。

「フロー図」だの「コード解説書」などの名前はどうでもいいです。重要なのは、部品と機能の対応表を残しておけ、という事です。

逆に言うと、部品と機能の対応が分からないような書類ばかりを作っていても、無駄です。

けっして、やみくもに「○○設計書」のような名前の書類をいくつも残すのではないべきです。目的である、「部品と機能の対応表」を忘れないようにしましょう。

IT業界でこういう書類を残しているか知りませんが、少なくとも電子回路の業界では、こういう書類を残しています。けっして、（ブラック企業だらけだと悪評高い）日本IT企業の習慣のマネではなく、世界に冠たる競争力をもつ日本のB to Bの電子機器の製造業の手法をマネしましょう。

一般の企業でのITソフトは、発売後から10年後や20年後にもメンテナンス等が必要な場合があるので、コードの全体構造の解説書が必要なのです。たかが1～2年で流行の廃れるソフトの管理手法なんか、手本にしてはいけません。

コード解説書を書かない場合、それでも将来的なリバースエンジニアリング予防のために解説を残したい場合には、おそらくですが、代わりに「仕様書」などの既存の種類に流用で、変数名や関数などの指定を記載したりする必要が生じるかもしれません。ソフトウェアの設計図（完成予想図）はその性質上、解説などはあまり長く書けません。それはそれで一つの方法です。勤務先などに応じて、うまく方法を選んでください。

しかし、個人製作ソフトの場合、仕様書は無いのが普通なので、簡易的にコード解説書を書いたほうが早いかもしれません。プログラミングは、仕事や学業などの都合で中断される場合もありますが、再開後に、中断前のアイデアなどを思い出すためにも、コード解説書は書かれていると便利です。（コレがないと、時間が経つと、ほぼ作業内容を忘れる。）

さて、経団連企業などの東証一部の上場企業のIT業界の人が「仕様書を書かないと、あとでコードの仕組みを忘れる」とか言ってるのは、きっと、このコード解説書のことでしょう。経団連発言の時代的な文脈的に、けっして要件定義書とか完成予想図とかのことではないハズなので、勘違いしないようにしましょう。

このコード解説書の書き方には、けっして、決まった書き方がありません（なので、市販の入門書では、紹介されてない）。ですが、ともかく、経団連企業とかの技術系企業の設計部門では、こういう書類も書くのが望ましいとされています。

重要なことは、コードのどの部分が、ソフトウェアのどのような機能を実現するために、何を構成しているかと言った情報を、コード解説書または仕様書などで残すことです。

システム構造の書き方

システム構造を解説するには、要するに変数名や関数名や、モジュールが、設計図に示した設計意図にどう対応しているかを、記載できれば良いのです。こういった大目的をまず忘れないようにしましょう。

では、どうやったら、こういう解説をできるのかを、これから考えていきましょう。

ソフトウェア開発前には実際のシステム構造（プログラムをどういう仕組みにしたとか、変数名をどうつけたか、とか）を書くのが難しいので、ある程度、開発が進んでから、開発中にシステム構造を書くことになります。

このコード解説書には、決まった描き方がありません。（なので、一般むけの「仕様書の書き方」入門書では、紹介されていない。）

なお、この「コード解説書」書類の呼び名は特に決まっていません。呼び名が無いと不便なので、とりあえず「コード解説書」と呼ぶことにします。

ファイルの解説を書く

まず、ソフトウェアのシステム構造を解説する場合、どのファイルがエントリポイント（コンパイル時に最初に呼び出されるファイル。Main関数などがある）なのか、そういうことから、コード解説書に書いてください。

C言語にはファイル分割という機能があり、ソースファイルを複数のファイルに分割できますので、実際のソフトウェアではファイルが何種類もできます。

なので、コード解説書にエントリポイントがどのファイルなのかを書いてないと、いちいち読者がファイルを開いて読まないと、どのファイルが最初に呼び出されるのかを理解できません。

※ 注意: 下記では読者の共通知識のためゲームソフトを例に説明しますが（製造業の話題だとIT系の人が理解できないので、ゲームソフトで喩えている）、しかし実際のゲーム業界でどうしてるかは知りません。下記の書き方は、IT企業や製造業組み込みソフトなどでのファイル内容説明の書類の書き方を、単純にゲームにそのまま当てはめただけの説明です。

ファイル分割されたファイルが幾つも（いくつも）ある場合、例えばゲームソフトだとして、ジャンルがRPGなら

wikiFantasy.cpp

battle.cpp

map.cpp

menu.cpp

などのようにファイルが幾つもある場合、

システム構造書に、

ファイルとその内容
 * wikiFantasy.cpp : このソフトのエントリポイント（最初に呼び出されるファイル）
 * battle.cpp : 戦闘処理のファイル
 * map.cpp : マップ処理（フィールドやダンジョンなど）のファイル
 * menu.cpp : 「道具」「装備」などのメニュー画面のファイル

などのように、それらのファイルが何を処理しているのかを第三者が分かるように書いてください。また、なるべく箇条書きで書くのが、読みやすくて便利でしょう。

当たり前に残すべきメモのように思えるかもしれませんが、しかしこういったメモが残されてない職場は多くあります。悪い見本です。とにかく、瑣末なことでリバース・エンジニアリングを後任者にさせないように書類を残す習慣をつけましょう。

ダメな一般IT企業だと本当によくあるパターンで、ファイル解説の書類など何も残ってないのに自社アプリのファイルサーバーには「system.cpp」などの漠然とした名前のファイルだけがいくつもある場合が時々よくあり、「systemって何のシステムだよ・・・」と後任者があきれたくなるファイル名のプログラムがいくつもある場合、これは大変にリバース・エンジニアリングの手間を発生させる、プログラマーにとってイヤなパターンです。

暗黙の前提ですが、画面名やファイル名などの名前を決める際には、具体的な名前をつけるべきです。

書籍『ゲームプランナー入門 アイデア・企画書・仕様書の技術から就職まで』によると、ゲーム業界でもそう指導されています。

ゲーム業界に限らず、一般のIT業界でも同様に具体的に命名するべきでしょう。つまり、「file1.cpp」とか「a.cpp」みたいなファイル名は厳禁です。また変数名でも「b」とか「variable1」（英語でvariableとは「変数」という意味）みたいな変数名は避けてもらいたいです。

なお、一般企業では箇条書きの説明をするとき、よくエクセルなどの表形式で説明することもあります。

変数名	内容	注記事項
wikiFantasy.cpp	このゲームのエントリポイント（最初に呼び出されるファイル）
battle.cpp	戦闘処理のファイル
map.cpp	マップ処理（フィールドやダンジョンなど）のファイル
menu.cpp	「道具」「装備」などのメニュー画面のファイル

のような表形式でよく箇条書きが書かれます。

開発した原作者には、「ファイル名から予想がつくだろ？」と当然に思うことであっても、意外と、通じない場合がありますので、きちんとコード解説書に、ファイルの処理内容を文章で書くべきです。

例えば、RPGの「メニュー」と言われても、あなたは「道具」「装備」などの画面を思い浮かべても、ほかの人は、戦闘シーンの「戦う」「逃げる」などのコマンド画面を思い浮かべるかもしれませんし、あるいは会話イベントの「はい」「いいえ」などの返事の選択画面を思い浮かべるかもしれません。

また、「マップ」 map と言われても、あなたは「主人公が現在いる場所の周囲」を思い浮かべても、ほかの人は、道具「地図」を使うと画面表示される世界マップと、世界地図のなかでの、主人公のいる地方の位置を思い浮かべるかもしれません。

または、「洞窟などのダンジョンの構造が書かれた地図のような道具が、そのゲームの中にあるのでは？」とか想像する人もいます。

このほか、数学用語で「map」（日本語でいう写像（しゃぞう）のこと）という用語がありますので、それと混同される場合もあります。

このように、ファイル名だけだと、いろいろと想像されてしまいます。

なのでコード解説書を作る場合、もし仕様書側に解説が無い項目なら、そのファイルのソースコードを読まなくても理解できるように、きちんとファイル内容の要約を解説書に書きましょう。

このほか、どうしても「System.cpp」とかのような漠然とした名前のファイルがある場合、何のシステムなのか、わかるように書いてください。（そもそも、そういう漠然とした名前を避けたほう安全ですが。）

パラメーターの名称と内容を書く

たとえばRPGを作るなら、

パラメータとその内容
 * chara_name : 勇者「イノウエ」や魔法使い「タナカ」などの名前
 * chara_level : 人物のレベル

 * hp : ヒットポイント
 * hp_max : 最大ヒットポイント

 * mp : マジックパワー
 * mp_max : 最大マジックパワー

 * sp : スキル パワー
 * sp_max : 最大スキル パワー

 * attack_power : 人物の攻撃力
 * defence_power : 人物の防御力

 * strength : 人物の腕力

 * magical_force : 人物の魔力
 * wise : 人物の賢さ
 * mental : 人物の精神力
（後略）

などのように、そのゲームで使うパラメーターについて、ひととおり、変数名と、その内容の要約を書いてください。

たとえ原作者には「当然だろ」と思えることであっても、他人には意外と通じません。

たとえば、「defence_power」と言われても、仮にアナタは「防御力」のことだと思っても、ある人は

「戦闘コマンド「防御」を選択したときのダメージ減少量なのか？」

とか、思うかもしれません。

また、防具の防御力と、人物の防御力とを、同じ変数にするか、違う変数にするのかどうかも、「defence_power」という名前だけでは分かりません。

でも「人物の防御力」というように要約があれば、「あっ、防具の防御力は、人物の防御力とは別の変数なんだな！」って分かります。

また、

magical_force : 魔力

wise : 賢さ

mental : 精神力

のような、魔法のような非現実的なファンタジーを前提にしたパラメーターがある場合、そのパラメータが何に影響をするのか、仕様書のほかの部分に書いてください。

例えば、

「魔力は、最大MPだけに影響するのか、それとも魔法の威力にも影響するのか？」とか、

「敵のつかった魔法攻撃で味方のうけるダメージに、魔力は影響するのか？」とか、

「賢さが増えると、魔法は強くなるのか？」とか、

「精神力は、賢さ と、どう違うのか？」とか、

上記の要約だけでは、疑問がどんどんと出てきます。

市販のRPGでも、「魔力」「賢さ」「精神」の数値が増えると、何に影響するかは、ゲームごとに違います。

つまり、

「このゲームでは、魔法の威力は、○○と△△によって決定される。」

「最大MPは、□□によって決定される。」

などのように、何によって決定されるのかを、書いてください。

もし要件定義書など別の書類に書いてあるなら、それを参照する形で簡略化してもいいですが、しかし要件定義書には一般に変数名（「attack_power」とか）は書かれていないので、やはり、こういうコード解説書も作っておくのが良いでしょう。

業界によっては、この変数名などの詳細を指定した書類を「プログラム設計書」と読んだりして区別する場合もあるが、業界や会社ごとに意味がバラバラなので、本ページでは、その呼び方（「プログラム設計書」）は用いないことにする。

たとえ、コード解説書の記述が、他の書類と説明がいちぶ重複していても、かまわないでしょう。

むしろ、他の書類と相互に照合することにより、設計ミスなどを見つけやすくなる場合もあります。

とはいえ、コードのすべてを解説するのも時間的に困難なので、説明に優先順位をつけ、設計者に必要なことを優先して書くようにしましょう。

なお、このコード解説書を書く場合、けっして単に「どこの変数の内容がいつ、どういう内容に変わる」とかだけを書くのではなく、その作業を通して何を実現しようとしているのか等の意図も、書くようにしましょう。

自分の書くコード解説書でバグのある内容を記述してしまうというミスをしてしまう場合もあります。なので、万が一、そういうミスをしてしまった場合に、将来的に仕様書を読まされる後輩たちが修正しやすくするためにも、できれば各コードの意図・目的なども併記するようにしましょう。

たとえ執筆時点でバグは無くとも、ソフトウェアによっては将来的にOSやらミドルウェアやらの変更が必要になったりする場合もあり、そういう場合に既存の仕様では動作しなくなる場合もあるので、仕様に変更の必要が生じる場合もあります。

もちろん、細かいことはソースコードにコメント文で書け済みますが、しかしもしソース側でかけないような事があれば、解説書の側で書くと良いでしょう。

なので、そういった将来のミドルウェア変更のような事態も見越して、特に重要になりそうな各プログラムがあれば、そのプログラムの作業内容の意図・目的なども、できれば、どこかに書いておきましょう。

とにかく、それぞれの書類で説明が他書類と重複していて説明文がやや増えても、説明の多いぶんには、デバッグが効率化するので問題ないのです。仕様書の分野では、説明の「大は小を兼ねる」です。

後任者は思考の経緯も知りたい

後任者が、仕様書や「要件定義書」や「○○設計書」などの各種の書類などを読むのは、仕組みを把握したり完成目標を確認する理由のほかにも、前任者の開発の経緯やそれにともなう思考の経緯を知りたいという理由もあります。

たとえば、もし古いソフトに不具合が出たときなどに、設計ミスなので設計変更が必要ですが、 後任者がどこの設計部分がどういう事情でそういう設計になったかが分からないと、後任者がどう設計変更でイジレナイからです。

（実際には書類不足などで前任者の意図が分からない場合も多く、そのため、テストを頻繁に繰り返すことになり、工期が増えて残業なども増えてしまったりします。）なので、もしも書類がうまく残っていて、前任者の「こういう理由で、こういう設計にしました」という設計者の思考の経緯が書類に残っていれば便利です。というか、それが無いと困ります。しかし困ったことに、無い場合が多いので、日本の技術者はよく困ります。

設計者の思考の経緯を伝えられるような、そういう定型の書類形式というのが、ありません。「要件定義書」、各種の「○○仕様書」、「△△設計書」などを見ても、そこには通常、思考の経緯は書かれていません。

「要件定義書」や「○○設計書」などは無いよりかはマシで、思考の経緯などを推測するヒントにはなりますが、あくまでヒントどまりです。 「部品と機能の対応表」のようなものがあれば、かなりヒントにはなりますが、しかし、それでもヒントどまりです。

なお「部品と機能の対応表」の目的は、けっしてヒント目的だけでなく、設計内容のチェック用資料や他ソフトなどとの連携をする際の資料なども兼ねています。なので、たとえ思考の経緯を残した書類を書けても、「部品と機能の対応表」の種類も書類作成を省略せずに作るべきです。

とにかく、後任者のために書類を残すとき、思考の経緯もうまく手短かに分かるように書類も作りましょう。

このコード解説書のページ数は特には決まっていませんが、おおむね、持ち運びやすい程度の厚さになるページ数にしておくべきでしょう。

よくあるトラブル: メンテ資料紛失

この手のメンテナス資料でよくあるトラブルが、退職エンジニアの資料紛失です。

会社の上司が、メンテナンス資料の定期チェックをサボりたいあまりに、担当エンジニア個々人のパソコンにだけ資料を保存させておいて、そのエンジニアが退職などしたときに資料が紛失するトラブルが日本各地で多発しています。（もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない場合が多い。）退職したエンジニアの使っていたパソコンは、次の新人のためにフォーマット初期化するので、フォーマットの際にメンテナンス資料も消えてしまうというトラブルです。

「会社の共有フォルダにメンテ資料を置きましょう」と提案しようにも、しかし上司のチェックすらされてない資料が共有フォルダに置かれるわけもないので、結局はそういう会社ではエンジニア個人のパソコンでメンテ資料を管理させられたりもします。そして、いつしかメンテ資料が消失しています。

対策

この手の資料消失のトラブルを未然防止する簡単な方法は、定期的に、部署の部長課長などや上司などの管理者が、現場エンジニアから上がってきたメンテナンス資料の原稿を、（管理者が）定期的にチェックする必要があります。

また、こうやって定期チェックすれば、万が一、メンテ資料消失しても、資料を普段から検査してきた上司や検査担当者の頭の中に記憶が残っているので、ノウハウの復旧が比較的に容易です。

解説

しかし、部長や課長などが原稿チェックを面倒くさがっていると、上述のようなトラブルになります。

どこの技術系の企業でも、設計図のチェックは念入りに行いますが、しかしメンテナンス用資料のチェックが省略されたりする会社が多くあります。 資料紛失は会社側の自業自得でもあります。

なお、上司がチェックを面倒くさがっているという理由でメンテ資料が個人管理されている場合、当然、その資料は印刷などはされていません（もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない）

なので、退職しなくても、ハードディスク故障などが起きればメンテ資料は消失して一巻の終わりです。

退職が決まったときに会社は引継ぎ資料をエンジニアに作成させようとしますが、当然、上述のような技術資料が急に作れるわけもなく、そもそも資料の内容が上司や同格の技術力のエンジニアから検証チェックもされてないので信頼性も不明だし、よって急ごしらえの資料作成は大抵、失敗に終わります。

根本的な原因は、メンテ資料のための作成費用を普段から出していなかった会社の態度です。また、この手の会社は、そもそも論として、退職エンジニアより昔の前任者からのメンテ資料すら用意していないのが通例です。そんな杜撰（ずさん）な管理体制なので、大抵の企業では、急ごしらえのメンテ資料の作成は失敗します。会社の自業自得です。

つまり資料消失であわてる会社というのは、そもそも、まともにメンテ資料の上司によるチェックもしていなかったという会社であり、いろいろと自業自得です。

「単位動作」という概念

主に機械工学教育の用語なのですが、「単位動作」という用語があります。

たとえば、熟練工の動作は、一見すると色んなスキルを習得しているので複雑に見えますが、しかし動作のひとつひとつは、たとえば卓上ボール盤なら教科書どおりの卓上ボール盤の使い方ですし、やすりがけ　の動作も、教科書どおりの動作です。

複雑な動作も、教科書どおりの動作を、組み合わせただけに過ぎません。

そして、その　やすりがけ　だけの動作の説明も、図や写真などを使って、「手順1：○○をする。」、「手順２：△△をする。」などと一段階ずつ、1ステップも抜かりなく 教えます。

だから、工業高校や大学の機械工作実習では、教科書どおりの動作をひとつずつ、教えます。

けっして、いっぺんにまとめて、別種の動作を教えません。

このように、動作をひとつひとつの単純な動作に分解することを単位動作といいます。

なぜ、わざわざこんな事を説明するかというと、世間では複雑な物事を説明するときなのに、いっぺんに教えたがる人がいます。しかし、そういう教え方は、多くの開発現場ではNG（エヌジー、ノー・グッド）です。

残念なことに、インターネット上には、一見すると説明書の文章量が多くても、実態を読むと、このような作者以外でないと操作方法を読み解けないようなダメな説明法をされているツールも、残念ながらネットに多く公開されてしまっています。

単位動作を意識した解説の書き方は、べつに難しくなく、普通に、 たとえばwindowsのオフィスソフトなどのヘルプファイルや、あるいはオフィスソフトについての市販の操作解説書のように、 「～～をしたい」といった操作目的の種類ごとに一個ずつ手順を段階的に教えればよいだけです。

単位動作の説明を軽んじる人が根本的に勘違いしていることは、「複雑な動作を練習したほうが、スキルが上達する」という勘違いです。

むしろ物理学の公式のように、単純で短いものに置き換えたほうが、物事を考える際の部品として使いやすくなるのです。 だから実際の順序は、「単純な動作を見つけ出すために、その何倍もの練習や試作をする」のです。たとえるなら、発明家の努力のようなものです。「99%の努力の上での、1%のひらめき」です。

実社会のデータベースでは過去データは消さない

在庫管理ソフトで、もし在庫部品データで、購入元メーカーで生産中止になったりした部品があっても、一切、在庫データベースからは登録を消しません。

もし消したりすると、次の登録番号の部品との登録情報の連続性が無くなり、登録データが飛び飛びになるので、大変に管理が難しくなるからです。

だからともかく、生産中止部品のデータベース管理では普通、その部品の末尾コメントに「生産中止」などと書き足すだけにして、登録そのものは維持します。

また、自分が使っていなくても、過去の自社製品を購入した客先がその部品を組み込まれた自社製品を使っている場合もありますので、残す必要があります。

だからもし、生産中止でなく単に入力ミスなどで登録済みの部品をまた登録してしまったことが判明した場合も、 最新の登録IDでない限りは、消すのではなく、末尾コメントに「登録ミス。すでにID○番で登録済み。」のような記録を書いて残したままにするのです。

こういうのはデータベースを運用する際の基本テクニックです。

製造業の図面などの「部品表」の番号でも、同じようなテクニックが使われます。設計変更により過去の廃止になった部品に当てられていた番号は、消すのではなく、新規の番号を確保して、その新規番号に代替の新部品を割り当てるというテクニックです。

また、「登録IDを最整列して並び替える」なんてことは、一切、しません。そもそも、在庫ソフトにそのような機能も原則、ありません。

なぜなら、すでに紙に印刷した実物の台帳に保管されている登録ID番号までを、在庫管理ソフトで書き換えることは不可能だからです。

一般に在庫の台帳は小さな事業所でも数千種類の在庫部品があるので、台帳にあるその数千種の再チェックをするのは時間の無駄なので、並び替えはしません。もし在庫番号の並び替えをすると、「本当に並び替え後の番号が合っているか？」などのチェックの手間が生じます。

品質の検証

製造業でもIT企業でも品質の検証は、部品ごとの検証と、全体の組立てをしたあとの検証という、最低でも2段階です。

少なくとも、自動車業界はそうです。

個々の材料部品などは、実際に引張り試験や荷重試験などを実際に物理実験を行い、部品の耐久値が規定や要求仕様を満たしているかを、事前に確認します。そして自動車の走行試験や衝突試験などは、実際に部品を組み立てて製品の状態である自動車にしてから走らせて見るしか、方法はありません。

チェックにおいて、シミュレーションなどは無駄です。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もありません。

「チェックの最終確認においてシミュレーションが無駄」といのは、これは自動車業界だけでなく、航空宇宙などでも同様です。日本のJAXAは「はやぶさ」の部品モジュールの開発において、実際に部品を組み立てたうえでの（シミュレーションではなく）物理実験をしています（※ 講談社ブルーバックス『小惑星探査機「はやぶさ」の超技術』で確認できます。）。

また、産業技術総合研究所での測定の国家標準器開発などでも同様の手法であり、実際に測定器を製品として組み立てた上での物理実験をしています（テレビ番組では、TBS科学番組『夢の扉』でメタンハイドレート採掘の産総研の研究者が、そうシミュレーションの問題点を指摘しました）。

ソフトウェアの開発では原理的に物理実験は無理ですが、それでも不具合対策の確認は、最終的には、実際にそのソフトをユーザー視点で使用してみる「実践」/「試用」しかありません。

ソフトウェア業界だと、個々の部品ごとにチェックすることを「単体テスト」といいます。一方、全体的に組みたててみてチェックすることを「ビッグバンテスト」と言います。

シミュレーションの目的はコストダウン投資

さて、チェックにおいて、シミュレーションなどは無駄であり。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もないのでした。

ではシミュレーションの意義は何かと言うと、工業系に強いライター（「文筆家」の意味）の山根一眞『メタルカラー』シリーズのどれかに書かれていると思いますが、意義はけっして直接のチェックではなく、既に行った物理的な検証実験をもとにそれをシミュレーションと照らし合わせることにより相互検証することで、検証回数を減らすことにより費用節約するのが目的です。

たとえばシミュレーションなしでは20台の機械装置を耐久実験のため壊さないといけない工程であると仮定して、もしシミュレーションありなら耐久試験で壊すのは12台ですむ工程にできるなら、今後の自社の新製品では8台ぶんの費用が節約できます。そういうコストダウン投資のためにシミュレーションをするのです。

品質テスト

ソフトウェアのテストは、IT企業では、よく新人がやらされる仕事でもあります。新人研修に組み込まれていたり、研修明けによく与えられる仕事でもあります。

なぜなら、自社ソフトウェアの内部構造の知識が乏しくてもテスト自体は可能だからです。

製造業などでも、多品種少量生産の設備機械そのものの生産では、たとえば簡易的な耐久試験などのために「実機のボタンAを押した後に画面遷移後にボタンBを押すのを、50回繰り返す」みたいな簡易的かつ長めの時間の繰り返しテストは、よく新人の仕事です。（なお、50000回の繰り返しみたいにテストが長すぎると人間じゃ無理だし（機械で繰り返すことになる）製品が磨耗して壊れたり製品寿命が大幅に減るので、せいぜい人間でも可能な500回くらいまでにとどめて、人間がテストしたりします。）

どの業界でも、テストのうち、時間の掛かる繰り返し試験は、よく新人に与えられる仕事です。

いちおう、設備機械の組立て直後の段階で、「ボタンAを1回だけ押すテスト。ボタンBを1回だけ押すテスト。」みたいな（繰り返しでない）短時間テストは、機械を組み立てした生産者本人が現場で行います。しかし、「500回繰り返す」みたいな仕事は長いので、新人がテスターを行うのがよくある会社風景です。

オーバーエンジニアリングを避ける

「オーバーエンジニアリング」（over engineering）という用語があり、善かれと思ってもか、余計な設計をしてしまう事です。」

たとえばソフトウェアの設計の場合、あらゆるバグを想定して個別に対応したコードを書こうようとしてしまうと、コードが長大になってしまい、保守性がいちじるしく低下してしまいます。

システムのあらゆる部分にバックアップを持つのも、時間的にも費用的にも不可能であり、オーバーエンジニアリングです。

製品と寸分も違わぬデザインパターンを追求しようとして、ろくに実装もしないのもあります。また、そのような発想で書かれたマニュアルは、膨大な学習コストが必要であり、実用性が乏しいです。

• MVP (Minimum Viable Product)

最小限の機能だけのプロトタイプを作る手法です。

生命などの安全にかかわるものでもないかぎり、失敗を許容しましょう。

• YAGNI (You aren't gonna need it、「そんなの必要ない」という意味）

機能が実際に必要になるまで追加しない方法です。

ソフトウェアの場合、あとからでも比較的に容易に追加できることが多いので、こっちのほうが良いでしょう。（ただし、航空宇宙や造船などは別かもしれません。）

「Premature optimization(早すぎる最適化)」も、オーバーエンジニアリングの典型例です。