コードに「墓標」を建てるな：なぜあなたのコメントは保守を阻害するのか
業務自動化の現場で、私は数多くの「死んだコード」を見てきた。特に、数年前に作られたであろうVBAプロジェクトを紐解くとき、そこには決まって「無意味なコメント」の残骸が散らばっている。
‘ 変数iを宣言する
Dim i As Long
‘ iに1を代入する
i = 1
これを見て諸君は何を感じるか？ 私には、ただの「時間の浪費」としか見えない。コードを見ればわかることをわざわざ日本語で書き直すのは、メンテナンスコストを倍増させるだけのノイズだ。
真に優秀なエンジニアは、コードで「何を（What）」記述し、コメントで「なぜ（Why）」を語る。今回は、チーム開発でバグを撲滅し、十年後も動く堅牢なコードを構築するための「コメントの極意」を伝授する。
—
1. 「何をしているか」はコードに語らせろ
良いコードは、それ自体がドキュメントである。変数名やメソッド名が適切であれば、コメントなど不要だ。
- Bad: `Dim a As Long ‘ カウンタ`
- Good: `Dim rowIdx As Long ‘ 最終行を取得するための行インデックス`
もし、コメントを消したときにコードの挙動が理解できなくなるなら、それはコードの設計が未熟であるというサインだ。コメントでごまかすな。リファクタリング（命名改善）で解決せよ。
—
2. コメントの極意：記述すべきは「制約」と「意図」
では、コメントはどこに書くべきか。答えは「コードだけでは読み取れない背景情報」だ。
A. 外部リソース（DB・API・ファイル）の制約
外部環境と連携する際、なぜその処理が必要なのかを記す。これは将来のトラブルシュートで命綱となる。
B. 特殊なアルゴリズムの回避策
バグ対応で「あえて非効率な書き方」や「奇妙な条件分岐」をしている場合、理由を書かなければ後任が「バグだ」と勘違いして修正し、地雷を踏むことになる。
—
3. 実践：保守性を極限まで高めたプロダクションコード例
以下は、外部CSVファイルを読み込み、データベースへインポートする堅牢な構造のサンプルだ。コメントの役割に注目してほしい。
‘ ==============================================================================
‘ 機能: CSVデータをDBへインポートする
‘ 注意: 実行前に「Microsoft ActiveX Data Objects 6.1 Library」を参照設定すること
‘ ==============================================================================
Public Sub ImportCsvToDatabase(ByVal filePath As String)
Dim conn As Object
Set conn = CreateObject(“ADODB.Connection”)
‘ 【意図】接続文字列に遅延バインディングを採用。
‘ 開発環境の差異（Office 32bit/64bit）を吸収し、動的な環境構築を避けるため。
conn.ConnectionString = “Provider=Microsoft.ACE.OLEDB.12.0;Data Source=” & _
Left(filePath, InStrRev(filePath, “\”)) & “;Extended Properties=’text;HDR=YES;FMT=Delimited'”
On Error GoTo ErrHandler
conn.Open
‘ 【制約】SQL標準関数ではなく、ACEドライバ特有の構文を使用。
‘ 高速化のためレコードセットを一括更新するが、メモリ消費が激しいため
‘ 1万行を超えるファイルは分割処理を推奨。
Dim sql As String
sql = “SELECT FROM [” & Mid(filePath, InStrRev(filePath, “\”) + 1) & “]”
‘ …（以下、DB書き込み処理）
Exit Sub
ErrHandler:
‘ 【意図】エラーログをイベントビューアではなく、ローカルのログに出力。
‘ ユーザーの権限でシステムログに書き込めない環境を想定。
Debug.Print “Error ” & Err.Number & “: ” & Err.Description
Resume Next
End Sub
—
4. チームへの提言：コメントルールを標準化せよ
私は大規模プロジェクトを統括する際、コメントに対して以下の3つのルールを厳守させている。
1. 「なぜ？」が書けないコメントは削除する
- コードの動作説明ではなく、設計判断の根拠のみを残す。
2. TODOコメントを放置しない
- `’ TODO: 後で直す` というコメントは、書いた瞬間にタスクチケットに変換せよ。VBEに残されたままのTODOは、腐った魚と同じだ。
3. 変更履歴（ヘッダーコメント）の廃止
- `’ 2023/10/01 氏名 修正` といった記述はGitやSVNなどのバージョン管理システムに任せろ。ソースコードの中に履歴を残すのは、履歴管理システムがない時代の遺物だ。
最後に
諸君、コメントは「コードが語りきれなかった設計思想の代弁者」であるべきだ。
コードは動くためにあるが、コメントは「未来の人間が、そのコードを恐れずに修正できるようにするために」ある。
次にコードを書くとき、一呼吸置いてこう自問してほしい。
「このコメントは、誰の、どんな不安を解消するために書くのか？」
その問いに答えられるなら、君のコードは必ずや堅牢なシステムへと昇華されるはずだ。現場からは以上だ。健闘を祈る。
