Excel VBA 逆引き集 | コメント規約

ねらい：コメント規約で「読みやすく・直しやすく・引き継ぎやすい」コードにする

VBAは簡単に書ける分、コメントがないと「何をしているのか分からない」「修正が怖い」状態になりがちです。コメント規約を決めておくと、誰が読んでも理解でき、初心者でも安心して修正できます。ここでは、基本ルールからテンプレートまで、例題を交えて解説します。

コメントの基本ルール

• 必ずOption Explicitの直下に「モジュール概要」を書く
• 処理のまとまりごとに「目的」をコメントする
• 変数宣言には「用途」を添える
• 複雑な式やアルゴリズムには「理由」を書く
• 更新履歴を先頭に残す（誰が・いつ・何を変更したか）

重要ポイント（深掘り）

• 「何をしているか」より「なぜそうしているか」を書く: コードを見れば「何」は分かる。コメントは「理由」を残すと価値が高い。
• コメントは最新に保つ: 古いコメントは害になる。修正時に必ず見直す。
• 短すぎず長すぎず: 1行〜3行で要点をまとめる。冗長は逆効果。

モジュール先頭コメントテンプレート

' ============================================
' モジュール名: ModEmployeeImport
' 役割: 社員データを入力シートから読み込み、検証して出力シートへ書き込む
' 作成者: 山田太郎
' 作成日: 2025-12-15
' 更新履歴:
'   2025-12-15 山田太郎 新規作成
'   2025-12-16 佐藤花子 検証ルールを追加（電話番号チェック）
' ============================================
Option Explicit

' ============================================
' モジュール名: ModEmployeeImport
' 役割: 社員データを入力シートから読み込み、検証して出力シートへ書き込む
' 作成者: 山田太郎
' 作成日: 2025-12-15
' 更新履歴:
'   2025-12-15 山田太郎 新規作成
'   2025-12-16 佐藤花子 検証ルールを追加（電話番号チェック）
' ============================================
Option Explicit

重要ポイント（深掘り）

• 履歴は必ず残す: 誰が何を変えたかが分かると安心。
• 役割を一言で: 「何をするモジュールか」が冒頭で分かる。

プロシージャ（Sub/Function）コメントテンプレート

'---------------------------------------------
' 名前: Run_EmployeeImport
' 目的: 社員データを読み込み、検証して出力シートへ書き込む
' 引数: なし
' 戻り値: なし
' 注意: Configシートに INPUT_SHEET, OUTPUT_SHEET が必要
'---------------------------------------------
Public Sub Run_EmployeeImport()
    ' 開始処理（画面更新停止）
    AppEnter "社員取込開始"
    
    ' データ読み込み
    Dim data As Variant
    data = ReadInput("Input")
    
    ' 検証処理
    ' 氏名必須、電話番号10〜11桁、スコア0〜100
    Dim clean As Variant
    clean = ValidateEmployeeData(data)
    
    ' 出力処理
    WriteOutput "Output", "A1", clean
    
    ' 終了処理
    AppLeave True
    MsgBox "社員取込が完了しました。"
End Sub

'---------------------------------------------
' 名前: Run_EmployeeImport
' 目的: 社員データを読み込み、検証して出力シートへ書き込む
' 引数: なし
' 戻り値: なし
' 注意: Configシートに INPUT_SHEET, OUTPUT_SHEET が必要
'---------------------------------------------
Public Sub Run_EmployeeImport()
    ' 開始処理（画面更新停止）
    AppEnter "社員取込開始"
    
    ' データ読み込み
    Dim data As Variant
    data = ReadInput("Input")
    
    ' 検証処理
    ' 氏名必須、電話番号10〜11桁、スコア0〜100
    Dim clean As Variant
    clean = ValidateEmployeeData(data)
    
    ' 出力処理
    WriteOutput "Output", "A1", clean
    
    ' 終了処理
    AppLeave True
    MsgBox "社員取込が完了しました。"
End Sub

重要ポイント（深掘り）

• 「目的・引数・戻り値・注意」を必ず書く: 入口で理解できる。
• 処理のまとまりごとにコメント: 「開始処理」「データ読み込み」など。

変数宣言コメントテンプレート

' 社員データ配列（ヘッダー＋行データ）
Dim data As Variant

' 検証済みデータ配列
Dim clean As Variant

' 出力先シート名
Dim outputSheet As String

' 社員データ配列（ヘッダー＋行データ）
Dim data As Variant

' 検証済みデータ配列
Dim clean As Variant

' 出力先シート名
Dim outputSheet As String

重要ポイント（深掘り）

• 変数は「何を入れるか」を明記: 型だけでは分からない。用途を添える。
• 配列やオブジェクトは特に重要: 中身が見えないのでコメント必須。

複雑な処理のコメント例

' 電話番号から数字だけ抽出
' 理由: ハイフンやスペースが混ざるため、数字のみを取り出して桁数を検証する
Private Function ExtractDigits(ByVal s As String) As String
    Dim i As Long, r As String
    For i = 1 To Len(s)
        Dim ch As String: ch = Mid$(s, i, 1)
        If ch Like "[0-9]" Then r = r & ch
    Next
    ExtractDigits = r
End Function

' 電話番号から数字だけ抽出
' 理由: ハイフンやスペースが混ざるため、数字のみを取り出して桁数を検証する
Private Function ExtractDigits(ByVal s As String) As String
    Dim i As Long, r As String
    For i = 1 To Len(s)
        Dim ch As String: ch = Mid$(s, i, 1)
        If ch Like "[0-9]" Then r = r & ch
    Next
    ExtractDigits = r
End Function

重要ポイント（深掘り）

• 「なぜこの処理が必要か」を書く: 単なるループは見れば分かる。理由が価値。

例題で練習

1. 例1: モジュール先頭に「役割・履歴」を書く。
2. 例2: Subに「目的・引数・戻り値・注意」を書く。
3. 例3: 変数宣言に「用途」を添える。
4. 例4: 複雑な処理に「理由」を書く。

実務の落とし穴と対策

• 落とし穴1：コメントが古いまま残る
  • 対策: 修正時に必ずコメントも更新。古いコメントは削除。
• 落とし穴2：コメントが冗長で読みにくい
  • 対策: 要点だけ。3行以内でまとめる。
• 落とし穴3：コメントが少なすぎて意味がない
  • 対策: 「目的」「理由」「用途」だけは必ず書く。
• 落とし穴4：誰が修正したか分からない
  • 対策: 履歴を残す。日付＋名前＋変更内容。

スターター手順（最短導入）

1. モジュール先頭に概要＋履歴を書く。
2. Sub/Functionに目的・引数・戻り値・注意を書く。
3. 変数宣言に用途コメントを添える。
4. 複雑な処理には理由コメントを入れる。
5. 修正時にコメントも必ず更新する。

初心者の方はまず「モジュール先頭コメント」と「Subの目的コメント」から始めてください。慣れてきたら変数用途や理由コメントを追加し、チームで共有できるコメント規約を整えると、コードが一気に読みやすくなります。