【テクニカル・上級編】コメントアウトの極意：コードの「意図」を残すための記述ルールとメンテナンス性 – Excel VBA解析バイブル

コメントアウトの極意：数ヶ月後の自分を救う「意図」のアーキテクチャ

レガシーシステムの保守現場において、最も恐ろしいものは「仕様書のないVBAマクロ」ではない。そこにあるのは、「何をしているかは読めばわかるが、なぜその実装選定に至ったのかが完全に隠蔽されたコード」である。

「動いているから触るな」の神話が生む技術的負債。その正体は、コードの行数ではなく、前任者（あるいは過去の自分）の「思考の欠落」に他ならない。本稿では、Excel VBAという極めて特殊なシングルスレッド環境において、メモリのライフサイクル、Windows APIの気まぐれ、そしてシステム間連携の泥臭さを生き抜くための「コメントアウトの極意」を伝授する。

—

1. 愚かなコメントと、至高のコメントの決定的な違い

初心者や中級者の書くコードには、次のような「無駄なコメント」が氾濫している。

‘ 2行目で変数を宣言している
Dim i As Long
‘ iを1から10までループさせる
For i = 1 to 10
‘ セルA1にiの値を入れる
Cells(i, 1).Value = i
Next i

これは罪悪ですらない。単なるノイズである。VBE（Visual Basic Editor）の構文を見れば、それが何をしているかは一目瞭然だからだ。シニアエンジニアが求めるコメントとは、「コードから読み取れない事実（ビジネスロジックの制約、APIの仕様、ハックの理由）」を記述したものである。

「なぜ（Why）」を残す黄金律

• × What: `Range(“A1”).Value = “Processed”` （A1に文字を入れている）
• 〇 Why: `Range(“A1”).Value = “Processed”` ‘ 競合防止のため、他端末からのポーリング処理に対してこのセルをロックフラグとして利用。詳細はチケット#4092参照。

この「Why」の有無が、数ヶ月後にシステム改修を行う際の工数を数倍から数十倍に変える。

—

2. 実践：極限環境を生き抜くコメント戦略とコード例

ここでは、実際の業務自動化で直面する「Windows APIの呼び出し」「メモリの明示的解放」「システム間連携（レガシーDB接続）」を想定し、意図が刻まれたコードのサンプルを提示する。

Option Explicit

‘ ==============================================================================
‘ モジュール名: modDataSync
‘ 概要: 外部基幹システム（Oracle）からの非同期CSVインポートおよびメモリ最適化処理
‘ 特記事項: 32bit/64bit環境両対応。APIのポインタサイズ差異に伴うクラッシュを回避する。
‘ ==============================================================================

If VBA7 Then
‘ 64bit環境対応のSleep API宣言
Private Declare PtrSafe Sub Sleep Lib “kernel32” (ByVal dwMilliseconds As Long)
Else
Private Declare Sub Sleep Lib “kernel32” (ByVal dwMilliseconds As Long)
End If

Public Sub ExecuteEnterpriseSync()
Dim cn As Object
Dim rs As Object
Dim wsTarget As Worksheet

‘ 【意図の記録】
‘ 画面描画とイベントを完全抑制し、ADO処理のスループットを最大化する。
‘ ※ エラー時に復元漏れを起こすとExcelが操作不能になるため、必ずError Handlerを通すこと。
Call ToggleSystemOptimization(False)

On Error GoTo ErrorHandler

‘ 【意図の記録】
‘ 外部Oracleドライバはメモリリークを起こしやすいため、
‘ CreateObject直後に必ずオブジェクト変数への参照保持と明示的な破棄ロジックを担保する。
Set cn = CreateObject(“ADODB.Connection”)
cn.ConnectionString = “Provider=MSDAORA;DataStore=PROD_DB;User ID=vba_user;Password=secret;”

‘ 【意図の記録】
‘ ネットワークの瞬間的な揺らぎによるTimeout対策。
‘ 基幹側のバッチ処理と競合する場合があるため、接続タイムアウトを60秒にハードコード。
cn.ConnectionTimeout = 60
cn.Open

Set rs = CreateObject(“ADODB.Recordset”)

‘ 【意図の記録】
‘ 一度全件をクライアント側にロードするとVBAのヒープ領域（約2GBの壁）を圧迫するため、
‘ サーバーサイドカーソル(adUseServer)を使用し、メモリ消費を最小限に抑える。
rs.CursorLocation = 2 ‘ adUseServer
rs.Open “SELECT FROM V_EXPORT_TARGET WHERE SYNC_FLG = 0”, cn, 0, 1 ‘ adOpenForwardOnly, adLockReadOnly

Set wsTarget = ThisWorkbook.Sheets(“Staging”)
wsTarget.Cells.Clear

‘ データ転送（一括CopyFromRecordsetによる高速化）
wsTarget.Range(“A2”).CopyFromRecordset rs

‘ 【意図の記録】
‘ 基幹システム側で「読込済みフラグ」を立てるためのバッチ連携クエリ。
‘ トランザクション分離レベルの都合上、SELECTとUPDATEのセッションを分ける必要があるため別コネクション。
cn.Execute “UPDATE V_EXPORT_TARGET SET SYNC_FLG = 1 WHERE SYNC_FLG = 0”

CleanUp:
‘ ————————————————————————–
‘ オブジェクトの明示的解放（ライフサイクル管理）
‘ COMコンポーネントの参照カウントを確実にデクリメントするため、
‘ Nothing代入の順序は Recordset -> Connection の逆順とする。
‘ ————————————————————————–
If Not rs Is Nothing Then
If rs.State = 1 Then rs.Close
Set rs = Nothing
End If

If Not cn Is Nothing Then
If cn.State = 1 Then cn.Close
Set cn = Nothing
End If

Call ToggleSystemOptimization(True)
Exit Sub

ErrorHandler:
‘ 【意図の記録】
‘ 予期せぬ例外時、デバッグ用にエラー番号と説明をイミディエイトに出力しつつ、
‘ ユーザーには業務継続不可能な旨を最低限のダイアログで通知する。
MsgBox “致命的なエラーが発生しました。管理者に連絡してください。” & vbCrLf & _
“Error: ” & Err.Description, vbCritical
Resume CleanUp
End Sub

Private Sub ToggleSystemOptimization(ByVal enableState As Boolean)
With Application
.ScreenUpdating = enableState
.Calculation = IIf(enableState, -4105, -4135) ‘ -4105=xlCalculationAutomatic, -4135=xlCalculationManual
.EnableEvents = enableState
.DisplayAlerts = enableState
End With
End Sub

—

3. 保守性を極限まで高めるためのコメント規約

現場のエンジニアとして、チーム全体で共有すべきコメントの規約を以下に定義する。これらはコードレビューの必須基準となるべきものである。

① 「ハック（泥縄式対応）」には必ず背景と期限を書く

VBAでは、Excelのバグや他システムとの不整合を回避するために「苦し紛れのコード」を書くことがある。その場合は必ず、なぜその汚いコードが必要だったのかを記述する。
> `’ [HACK 2023-10] Excelのバグにより、特定のWindowsパッチ適用下でClipboardメソッドがクラッシュするため、DoEventsを挟んでリトライする冗長構造にしている。パッチKBXXXXXXXが適用されたら削除可能。`

② マジックナンバーの意図を定義する

コード中に突如現れる数値（例: `-4135` や `Timeout = 60`）は、定数化するかコメントで意味を解説しなければならない。定数名が自明でない限り、その数値を選定した根拠（OSの仕様、DBの制限など）を添える。

③ 変更履歴ではなく「バージョン管理システム」を信じろ

コメントの中に以下のような変更履歴を長々と書く開発者がいるが、それはGitやSVNの仕事である。
> `’ 2023/01/01 田中 処理追加`
> `’ 2023/05/12 鈴木 バグ修正`

VBAであってもGitで管理すべきであり、コード内のコメントは「現在のコードがなぜこの形をしているか」の記述に専念させるべきだ。過去の過ちはログに任せ、現在と未来のロジックに集中せよ。

—

終わりに：コメントは「未来の自分へのラブレター」ではない、「冷徹な免責事項」である

数ヶ月後、あるいは数年後。あなたが異動や退職をした後、そのコードを引き継いだエンジニアが夜中に冷や汗を流しながらVBEを開く。その時、そこに書かれた的確なコメント（意図、制約、ハックの背景）は、彼らにとっての唯一の救いとなる。

優れたコメントとは、感情的なものではない。システムという巨大な迷宮において、迷子にならないための論理的な地図とコンパスである。コードを書き殴る手を一度止め、「なぜ私はこの構文を選んだのか」を数行の英語または日本語で刻み込むこと。それこそが、プロフェッショナルなVBAエンジニアのプライドなのである。