【VBA】バージョン管理とコメント戦略｜長期運用に強いプロジェクトの作り方

VBAは“ちょっとした自動化”から始まることが多いですが、
気づけば数年運用されるシステムになることも珍しくありません。

そのときに重要になるのが バージョン管理とコメント戦略。

本記事では、
現場で本当に役立つ実践的な管理方法 をわかりやすく整理します。

1. バージョン管理の基本方針 ― どこに何を記録する？
2. バージョン番号の付け方 ― 迷ったら“3段階ルール”
- ▼ 例：1.4.2
- ▼ 更新の基準
3. コメント戦略 ― “書くべき場所”と“書くべきでない場所”
- ▼ コメントは「補足」であり“説明書”ではない
4. 書くべきコメントの種類
5. 書かない方がよいコメント
6. モジュールの先頭に“ヘッダーコメント”をつける
- ▼ 推奨テンプレート
7. 変更履歴（ChangeLog）を管理する
- ▼ 推奨例
8. Gitを使う場合のポイント（任意）
- ▼ おすすめ方法
9. まとめ

1. バージョン管理の基本方針 ― どこに何を記録する？

VBAにはGitのような標準機能がないため、
「どこに、何を書いて、どう管理するか」 が極めて重要です。

▼ 推奨するバージョン管理の置き場所

① ThisWorkbook にバージョン情報を記載
② 専用モジュール（mdlVersion）を作る
③ ファイル名にバージョンを含める場合は最低限に

▼ 推奨する記載例（ThisWorkbook）

'Version: 1.4.2
'LastUpdate: 2025-05-12
'Author: Tanaka
'Summary: 売上データ自動集計ツール

▼ 記録すべき最低限の情報

バージョン番号
最終更新日
更新担当者
主な変更点（1〜2行）

これを付けるだけで、

「どのファイルが最新？」「どんな変更をした？」
という混乱が劇的に減少します。

2. バージョン番号の付け方 ― 迷ったら“3段階ルール”

VBAのバージョン番号は統一していない現場が多いですが、
おすすめは Major.Minor.Revision の3段階。

▼ 例：1.4.2

1：大きな仕様変更（互換性が変わる）
4：機能追加、改善
2：バグ修正、微調整

▼ 更新の基準

シート構造変更 → Major
ボタン追加、処理追加 → Minor
軽微な修正 → Revision

これをチーム内で統一すると混乱がなくなります。

3. コメント戦略 ― “書くべき場所”と“書くべきでない場所”

▼ コメントは「補足」であり“説明書”ではない

最も重要なのは、コードを読めば理解できる構造にすること。
そのうえで、必要なところだけコメントします。

4. 書くべきコメントの種類

① “意図”を書くコメント（最重要）

コードの意味ではなく なぜそうしたのか（理由） を書く。

'TODO: 来期の仕様変更で削除予定（2025/04）

'FIXME: 処理速度が遅いため後日改善

② 仕様や前提条件を書くコメント

「どんなデータが入る想定か」「例外は？」など。

'前提：売上データは1行目がヘッダー

③ 戻り値・引数の意味を書く（Function）

'引数：arr 数値配列
'戻値：合計金額

④ 一時対応のコメント（必ず期限を書いておく）

'TEMP: 2025年3月までの特別対応

5. 書かない方がよいコメント

❌ コードをそのまま言い換えたコメント

i = i + 1    'iを1増やす   ←不要

❌ 読めばわかる内容

Set ws = ActiveSheet  'アクティブシートをセット ←不要

❌ 使われなくなったコードの大量コメントアウト

'Call OldProcess
'Call OldProcess2
'Call OldProcess3

残しても邪魔なだけなので削除すべき。

6. モジュールの先頭に“ヘッダーコメント”をつける

どのモジュールも役割がわかると保守性が爆上がりします。

▼ 推奨テンプレート

'=============================================================
' Module: mdlData
' Role: 売上・顧客データの取得処理を集約
' LastUpdate: 2025-05-10
' Author: Tanaka
'=============================================================

誰が見ても“何のモジュールか”が一目でわかるのが理想。

7. 変更履歴（ChangeLog）を管理する

簡易的なログをモジュール内、またはThisWorkbookに残す。

▼ 推奨例

'【ChangeLog】
'2025-05-10 v1.4.2 売上の計算ロジックを修正
'2025-04-21 v1.4.1 出力処理の不具合を修正
'2025-04-12 v1.4.0 新規機能：月次レポート追加

長期運用では非常に効く。

8. Gitを使う場合のポイント（任意）

VBAでもGit管理は可能です。

▼ おすすめ方法

エクスポートした.bas・.cls・.frm をGit管理
ファイル名をプロジェクト構造に揃える
変更前後の差分をチェックしやすい

チーム開発の場合はほぼ必須。

9. まとめ

保守・改修しやすいVBAのための
“バージョン管理とコメント戦略”のポイントは以下の通りです。

✔ バージョン情報は必ずファイル内に残す

✔ バージョン番号は Major.Minor.Revision で統一

✔ コメントは「意図」を書くのが最重要

✔ モジュールのヘッダーコメントは必須

✔ 一時対応のコメントには期限・理由を書く

✔ ChangeLog で変更履歴を簡易管理

✔ Git併用でさらに強固な管理が可能

VBAは“軽いツール”だからこそ、
しっかり管理すると 長く安全に使える業務資産 になります。