VBAマクロ開発で最初に作る5種類の設計資料

コードを書く前に業務を見える形にするための資料体系

本資料は、出典を明記いただければ、商用・非商用を問わず、ご自由に複製・改変・再配布していただけます。なお、著作権表示は改変せず、そのまま記載してご利用くださいますようお願いいたします。

記事要約

Excel VBAの業務マクロは、コードだけを見ても全体を理解できません。入力ファイル、Excelブック内のシート、作業表、出力帳票、業務上の判定、既存コードの呼び出し関係が重なって、ひとつの小さな業務システムになっているからです。

この記事では、業務マクロを開発するとき、または既存マクロを調査するときに最初に作るべき5種類の設計資料を整理します。目的は、詳しい作り方をすべて説明することではありません。これから業務マクロ開発を実務として担当する人が、「何を資料として持っていなければ開発が危ないのか」を判断できるようにすることです。

ここで扱う5種類の資料は、全体概要図・データフロー図、項目定義書、決定表・判定条件表、関数解析資料、補助分析資料です。この5つを持つと、コードを書く前に、何を入力し、どこで加工し、何を出力し、どの条件で判断し、既存コードのどこを読めばよいかが見えるようになります。

本記事の対象とゴール

想定読者

Excel VBAの基本文法は分かるが、業務マクロの設計や既存マクロ調査に不安がある人
コードを書き始める前に、どの資料を作ればよいか整理したい人
引き継がれたExcelブックやVBAコードを、どこから読めばよいか分からない人
業務担当者と開発者の間で、マクロの仕様を共有したい人

本記事で得られること

業務マクロ開発で最初に作るべき資料の全体像が分かります。
各資料が「何を説明するものか」を区別できます。
コード、シート、項目、条件、検証をばらばらにせず、ひとつの開発手法として扱えるようになります。

本記事で扱わないこと

VBA文法そのものの解説
各資料の詳細テンプレート
実際のコード例
180ページ規模の書籍本文としての詳細解説
特定案件の個別設計

先に結論

Excel VBAの業務マクロ開発では、コードを書く前に、少なくとも5種類の資料を意識する必要があります。

1つ目は、全体概要図・データフロー図です。これは、マクロ全体を「データと場所の地図」として見る資料です。どの入力ファイルを使い、どのシートやテーブルを通り、どの出力を作るのかを示します。

2つ目は、項目定義書です。これは、入力項目の意味と、出力項目の作り方を定義する資料です。列名だけでは分からない業務上の意味、固定値、計算、変換、空白の扱いを整理します。

3つ目は、決定表・判定条件表です。これは、If文の連鎖を業務ルールとして外に出す資料です。条件、結果、処理を表にすることで、コードを読めない人でも判断内容を確認できるようにします。

4つ目は、関数解析資料です。これは、既存VBAコードを読むための資料です。関数一覧、コールツリー、アマルガムソースを使い、処理の入口、呼び出し関係、変更影響を見ます。

5つ目は、補助分析資料です。これは、標準の資料だけでは説明しきれない差異、方式案、比較検証、判断根拠を補う資料です。ウォーターフォール分析、旧新比較、手作業比較、方式案などがここに入ります。

この5つを全部同じ重さで作る必要はありません。重要なのは、業務マクロを「コードだけでできているもの」と見ないことです。Excelブック、業務データ、判定条件、既存コード、確認方法を、開発前に見える形へ分けることが重要です。

1. 業務マクロは小さな業務システムである

Excel VBAマクロというと、ボタンを押すと処理が走る小さな自動化のように見えます。しかし実務で使われる業務マクロは、単なるコードではありません。

入力ファイルがあります。作業シートがあります。マスタがあります。設定表があります。出力帳票があります。担当者が手作業で確認する画面もあります。さらに、古いマクロであれば、どの処理が本当に使われているのか、どの関数が古いまま残っているのかも分かりにくくなっています。

つまり、業務マクロはExcelブックの中に作られた小さな業務システムです。VBAコードはその一部であり、全部ではありません。

この見方を持たないまま開発すると、コードは書けても、業務として正しいかどうかを確認できません。どの入力を使うのか、どの列を見ているのか、どの条件で除外しているのか、なぜ旧マクロと結果が違うのかを説明できなくなります。

最初に伝えたいのは、ここです。業務マクロ開発では、いきなりVBAを書くのではなく、まず業務を資料に分けて見る必要があります。

2. 全体概要図・データフロー図は、データと場所の地図である

最初に作る資料は、全体概要図・データフロー図です。

これは、マクロ全体を一枚の地図として見る資料です。何を入力し、どのシートに入り、どこで加工し、どこへ出力するのかを示します。

ここで大事なのは、関数の細かい呼び出し関係を書き込まないことです。全体概要図は、処理の親子関係を見る資料ではありません。データが存在する場所、データが移る方向、業務担当者が確認できる場所を整理する資料です。

たとえば、入力CSVがあり、それを入力シートへ取り込み、作業シートで整形し、マスタを見て判定し、出力シートを作るとします。このとき全体概要図には、入力CSV、入力シート、作業シート、マスタ、出力シート、出力ファイルを書きます。

シートだけではなく、見えないデータもあります。VBAのPublic変数、配列、Dictionary、Collectionなどです。これらは画面に見えませんが、処理の途中で重要な状態を持っている場合があります。ただし、全体概要図ではそれらを主役にしすぎません。主役は、あくまで業務データが置かれている場所です。

全体概要図があると、関係者に説明しやすくなります。業務担当者には「この入力からこの出力ができます」と説明できます。開発者には「このシートが作業領域で、このテーブルがマスタです」と説明できます。既存マクロを読むときには「まずどの入口からどの出力へ向かうのか」を押さえられます。

全体概要図は、コードを書くための図というより、コードを読む前に迷子にならないための地図です。

3. 項目定義書は、列の意味と出力の作り方を固定する資料である

次に必要になるのが、項目定義書です。

Excelの業務マクロでは、列名だけを見ても意味が分からないことがよくあります。得意先、請求先、部門、計上日、処理日、締日、区分、コード。こうした項目は、名前だけでは業務上の意味が足りません。

項目定義書では、入力項目の意味と、出力項目の作り方を分けて考えます。

入力仕様は、入力データの説明です。列名、列位置、型、形式、必須かどうか、空白の扱い、コードの意味などを書きます。これは、外から受け取るデータをどう理解するかの資料です。

転記仕様は、出力項目の作り方です。出力の列を起点にして、どの入力列から作るのか、固定値なのか、計算するのか、条件によって変わるのか、空白にするのかを書きます。

この2つを混同すると、設計が崩れます。入力仕様は「受け取るデータの意味」です。転記仕様は「作るデータの作り方」です。似ていますが、役割は違います。

項目定義書がないと、開発者はコードの中で列の意味を推測することになります。推測でコードを書くと、動いているように見えても、業務上は間違っている可能性があります。

逆に、項目定義書があると、テストもしやすくなります。入力がこうなら、出力はこうなるはずだ、という期待結果を作れるからです。旧マクロと新マクロの結果が違うときにも、どの項目の仕様で差が出たのかを説明できます。

4. 決定表・判定条件表は、If文を業務ルールとして外に出す資料である

業務マクロで複雑になりやすいのは、条件分岐です。

対象にするか、除外するか。請求するか、しないか。エラーにするか、警告にするか。A区分ならこの処理、B区分なら別処理。こうした判断は、VBAではIf文やSelect Caseとして書かれます。

しかし、If文のままでは業務担当者が確認できません。コードを読める人しか条件を見られないからです。

そこで、決定表・判定条件表を作ります。これは、条件と結果を表にした資料です。

たとえば、条件列に「取引区分」「金額」「請求対象フラグ」「除外理由」を置き、結果列に「出力する」「出力しない」「警告にする」「エラーにする」を置きます。処理列には、その判断で何をするのかを書きます。

決定表で大事なのは、業務ルールとプログラム都合を分けることです。

請求対象かどうかは業務ルールです。空行を飛ばす、ヘッダー行を除外する、集計行を無視する、といった処理はプログラム都合です。これらを混ぜると、業務変更なのか実装上の都合なのかが分からなくなります。

決定表は、テストケースにもなります。条件の組み合わせを見れば、どの入力を用意して、どの結果を期待するかが分かるからです。

業務マクロを作るとき、If文が増えてきたら、それはコードを書くタイミングではなく、条件を外に出すタイミングです。決定表にできないIf文は、まだ業務ルールとして整理できていない可能性があります。

5. 関数解析資料は、既存コードを読むための地図である

新規開発だけなら、資料を作りながらコードを書けばよいかもしれません。しかし実務では、既存マクロの改修が多くあります。

既存マクロでは、最初にコードを全部読もうとしてはいけません。VBAの標準モジュール、シートモジュール、クラスモジュール、イベント、ボタン、共通関数が混ざっているため、順番なしに読むと迷います。

そこで作るのが、関数解析資料です。

関数解析資料には、関数一覧、コールツリー、アマルガムソースがあります。

関数一覧は、コード全体の索引です。どのモジュールに、どのSubやFunctionがあるのかを書きます。PublicかPrivateか、引数は何か、どのシートを参照するか、どのシートを更新するかも見ます。

コールツリーは、処理と呼び出しの地図です。ボタンやイベントやPublic Subを入口にして、どの関数がどの関数を呼ぶのかを追います。

ここで、縦方向と横方向を分けて見ます。縦方向は、入口、読込、正規化、判定、変換、出力、保存へ進む大きな流れです。この流れでは、入力シート、作業シート、確認シート、出力シートへ関心が移っていくことが多くあります。

横方向は、同じ処理段階にぶら下がる詳細処理です。読込処理にぶら下がるチェック、変換処理にぶら下がる補助関数、出力処理にぶら下がる整形などです。

この縦横の話は、全体概要図の話ではありません。全体概要図はデータと場所の地図です。コールツリーは処理と呼び出しの地図です。この2つを混ぜると、図が何を説明しているのか分からなくなります。

アマルガムソースは、分割されたVBAソースをひとつにまとめた解析用ソースです。AIに読ませる場合や、呼び出し関係をまとめて見たい場合に役立ちます。ただし、元のモジュールとの対応を失ってはいけません。

関数解析資料は、既存コードをそのまま顧客向け設計書にするためのものではありません。内部調査資料です。ここで分かったことを、全体概要図、項目定義書、決定表、補助分析資料へ戻していくことが重要です。

6. 補助分析資料は、説明しきれない差異と方式判断を受け止める資料である

全体概要図、項目定義書、決定表、関数解析資料があっても、それだけでは説明できないことがあります。

たとえば、旧マクロと新マクロで金額が違う。手作業結果とマクロ結果で件数が違う。業務担当者に、なぜこの方式で処理するのか説明しなければならない。こうした場面では、補助分析資料が必要です。

補助分析資料は、標準資料だけでは説明しきれない差異、方式案、比較検証、判断根拠を補う資料です。

代表的なものがウォーターフォール分析です。これは、開始値から終了値までの増減理由を並べる資料です。前回値から今回値、旧結果から新結果、手作業結果からマクロ結果へ、どの要因で増え、どの要因で減ったのかを説明します。

もうひとつ重要なのが方式案です。方式案は、仕様そのものではありません。仕様は、項目、条件、形式、期日などの具体的な決まりです。方式案は、それをどう実現するかの考え方です。

業務マクロでは、厚い基本設計書を毎回作るわけではありません。しかし、どういう考え方で処理するのか、どのデータを基準にするのか、どの判定を先に見るのか、どこまでを自動化し、どこを手作業確認に残すのかは、短くても残す必要があります。

ウォーターフォール分析と方式案は、同じ階層の補助資料です。ウォーターフォール分析は差異の説明に強く、方式案は実現方針の説明に強い。どちらも、標準資料だけでは足りない部分を補うために作ります。

補助分析資料は、全案件で必須ではありません。金額、残高、請求、入金、在庫のように説明責任が重い案件では重要になります。一方で、単純な整形マクロでは、簡単な方式メモだけで足りることもあります。

7. 5種類の資料は、順番に作るより、行き来しながら育てる

ここまで5種類の資料を説明しましたが、実務では一度で完成するわけではありません。

最初に全体概要図を作ります。そこで入力、シート、出力を見ます。次に項目定義書を作ろうとすると、列の意味が分からないことに気づきます。決定表を作ろうとすると、条件の優先順位が曖昧なことに気づきます。関数解析資料を作ると、見えていなかったPublic変数や共通関数が出てきます。補助分析資料を作ると、旧マクロとの差異や方式判断の根拠が必要になります。

つまり、この5種類の資料は、直線的に一回だけ作るものではありません。行き来しながら育てるものです。

全体概要図で見つけた作業シートは、項目定義書につながります。項目定義書で見つけた判定項目は、決定表につながります。決定表で見つけた複雑な条件は、関数解析資料で対応する関数を探す材料になります。関数解析資料で見つけた差異や不明点は、補助分析資料へ移ります。

この行き来ができるようになると、業務マクロ開発はかなり安定します。コードを書く前に、何が分かっていて、何が分かっていないかを分けられるからです。

8. まとめ

細かいテンプレートより先に、次の考え方を渡すのがよいです。

業務マクロは、コードだけではなく、Excelブック、業務データ、条件判断、既存処理、検証方法が組み合わさった小さな業務システムです。

だから、開発では最初に5種類の資料を意識します。

全体概要図・データフロー図は、データと場所の地図です。

項目定義書は、列の意味と出力の作り方を固定する資料です。

決定表・判定条件表は、If文を業務ルールとして外に出す資料です。

関数解析資料は、既存コードを入口、縦方向、横方向から読むための資料です。

補助分析資料は、差異、方式案、比較検証、判断根拠を説明する資料です。

この5つを作る目的は、きれいな設計書を増やすことではありません。開発前に迷子にならないこと、業務担当者と開発者が同じものを見ること、改修時に壊してはいけない場所を見つけること、結果の差異を説明できるようにすることです。

まずは、この5種類の名前と役割を覚えれば十分です。詳細な書き方は、その後でひとつずつ学べばよいです。

Excel VBAマクロ開発で最初に必要なのは、いきなりコードを書く力ではありません。業務を資料に分けて見る力です。

全体概要図で、データと場所を見る。項目定義書で、列の意味と出力の作り方を見る。決定表で、業務判断を見る。関数解析資料で、既存コードの入口と流れを見る。補助分析資料で、差異、方式、比較、検証を見る。

この5種類の資料を持つと、Excel VBAマクロは、単なるコードの集まりではなく、説明できる業務システムとして扱えるようになります。

最初の段階では、細かいテンプレートよりも、この見取り図が重要です。どの資料を見れば何が分かるのか。その感覚を持てれば、実際の設計書や既存マクロ調査へ進める土台ができます。

出典メモ

本記事は、次のMarkdown原案をもとに、LWP記事用の技術概念型記事として再構成したものです。

入力元: C:\Users\hoehoe\Downloads\excel_vba_macro_design_research_outline.md
原案の主題: Excel VBAマクロの設計および既存マクロ調査において作るべき5種類の資料
記事化方針: 180ページ書籍目次の詳細化ではなく、開発手法の概要を伝える4から5ページ相当の記事として再構成