コメントアウトの極意：VBAを「負の遺産」にしないための設計思想
多くのエンジニアが勘違いしていることがある。コメントとは「コードの説明書」ではない。
コードとは、それ自体が論理を雄弁に語るべきものだ。では、なぜコメントが必要なのか。それは、コードが語れない「文脈（コンテキスト）」と「制約（コンストレイント）」を後世に残すためである。
特に、Windows APIを叩き、メモリリークの淵を歩くようなVBA開発において、コメントは「技術的負債」を「資産」に変えるための唯一のメタデータだ。本稿では、レガシーを掌握し、保守性を極限まで高めるためのコメント術を伝授する。
—
1. 「何をしているか」を書くのは罪である
`i = i + 1 ‘ 変数iを1増やす`
このようなコメントは即座に削除せよ。コードを読めない人間に合わせる必要はない。我々が記録すべきは「なぜこの処理がこのタイミングで必要なのか」という「設計の意思決定の記録」だ。
記述の黄金律：なぜ（Why）＞ 何（What）
- Why: なぜこのAPI呼び出しが必要なのか？（例：標準機能ではメモリ解放が不完全なため）
- What: 何が起きるのか？（例：一時的にExcelの再描画を停止する）
- Constraints: どのような制約下にあるのか？（例：64bit版Officeでのポインタ差異）
—
2. 現場で使える「アーキテクト流」コメント実装例
例えば、ExcelからWindows APIを呼び出し、特定のハンドルを操作する際のコメント記述例を見てほしい。単なるコードではなく、将来の自分への「警告」を含めるのがコツだ。
‘ ==============================================================================
‘ [機能]: 指定ウィンドウのハンドルを取得し、メモリキャッシュを強制解放する
‘ [背景]: 32bit環境ではGCが正常に機能せずメモリリークが発生するバグへの対抗策
‘ [制約]: 64bit環境ではポインタサイズが異なるため、PtrSafe宣言必須
‘ ==============================================================================
If VBA7 Then
Private Declare PtrSafe Function SetProcessWorkingSetSize Lib “kernel32” _
(ByVal hProcess As LongPtr, ByVal dwMinimumWorkingSetSize As LongPtr, _
ByVal dwMaximumWorkingSetSize As LongPtr) As Long
Else
Private Declare Function SetProcessWorkingSetSize Lib “kernel32” _
(ByVal hProcess As Long, ByVal dwMinimumWorkingSetSize As Long, _
ByVal dwMaximumWorkingSetSize As Long) As Long
End If
Public Sub OptimizeMemory()
‘ 目的: Windowsのメモリ管理機構に空きメモリの解放を指示する
‘ 理由: 大規模なデータ処理後、Excelがメモリを専有したまま解放しない挙動を抑制するため
‘ 注意: 高頻度での実行はOSのディスクスワップを誘発しパフォーマンスを低下させる
Dim hProcess As LongPtr
hProcess = -1 ‘ 現在のプロセスを指定
‘ API呼び出し：値を最小値(-1)にすることで物理メモリのコミットを解除
Call SetProcessWorkingSetSize(hProcess, -1, -1)
‘ 重要: ここでエラーハンドリングを怠ると、API呼び出し失敗時に
‘ Excelが異常終了するため、呼び出し直後の戻り値判定を強制すること
End Sub
—
3. レガシー保守における「埋め込み警告」の技術
数年後の君がこのコードを見たとき、最も恐怖するのは「なぜこの処理が消せないのか」という疑問だ。
- 「消せない理由」を明記する: 「互換性のために残しているが、〇〇環境以降は廃止可能」といった具体的な条件を残せ。
- バグの「生存記録」: 「過去にここで無限ループが発生し、〇〇の条件で回避した」という経緯は、後の不具合再発を未然に防ぐ防波堤となる。
‘ 修正履歴: 2023/10/01 担当: 〇〇
‘ 変更理由: APIの呼び出しタイミングをループ外に出すと動作が不安定になるため、
‘ 敢えて非効率だがループ内実行を維持。これを最適化してはいけない。
—
4. チーフアーキテクトからの提言
コードは書かれた瞬間から腐敗が始まる。しかし、適切なコメントがあれば、その腐敗の進行速度を遅らせることができる。
1. TODOは期限付きで: `TODO: 後で直す` は無意味だ。`TODO: 2024/03末のAPI仕様変更後に見直す` と書け。
2. マジックナンバーには文脈を: 数値の意味だけでなく、その数値がどこから導き出されたのか（例：`’ 測定値に基づき、オーバーヘッドを考慮して100ms待機`）を記録せよ。
3. コードを消す勇気: コメントで「ここは不要」と書く前に、そのコード自体を削除せよ。残っているコードはすべて「生きている証」でなければならない。
VBAはレガシーだが、それを扱うエンジニアの技術までレガシーであってはならない。
「なぜ」を語るコードを書き、後世のエンジニアに感謝されるアーキテクチャを築け。それが、真の自動化エンジニアの責務である。
