元エンジニアが実践しているプログラミングのコメントの使い方をまねしたらすごかった

プログラミングの時にコメントを有効に使っていますか？私なりの方法をご紹介したいと思います。

プログラミング教室に通ったりエンジニアとして就職した経験があるわけでは無いので、まだまだ使い方はあるかもしれませんが、そんなときはどうぞご教示下さい。

この記事は初心者～中級です。
レベルについてはExcel VBAの実力（レベル）を定義してみる　初心者～三段をご参照ください。

目次

コメントはいろいろな使い方がある

コメントはプログラミングを書くところに記述する、コードが実行される際には無視されるメッセージです。無視されると言うことは自由に記述できると言うことです。私が少しずつ思いついたり、他の人のコードを見る中で学んだ使い方を共有していきます。

コメントそのものの書き方は、それぞれプログラミング言語で違うので、そちらの解説記事に譲ります。

リリース後も残しておくメモ

自分用のメモ（残すタイプ）

変数や定数などの説明

まず一つは自分用のメモです。簡単な繰り返し構文でも入れ子の中に入れ子があってさらにIfが入れ子になったりしていると、後から処理を見たときに何をしているのか解読に時間が掛かってしまいます。

業務効率化のためにプログラミングをしているのであれば、そのプログラミングの作業も効率化していきましょう！

例）VBAの場合

Sub SampleProgram()

    'ヘッダの列番号は固定なので、「売上数量」の列番号を定数で宣言する
    Const 受注数量clm As Long = 3
    
End Sub

この場合はメンテナンス性UPや人への説明も兼ねているので、リリース時も残しておくと良いと思います。

処理の流れ

下の人への連絡を兼ねる場合もあります。人が読むことを想定するまとまった情報の場合、わたしは「>>>>」と「<<<<」で囲むという独自のルールを作っています。

Sub SampleProgram()
'>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
'このプロシジャは①受注データ取得、②宣言した配列に格納、③受注データを保存せずに閉じる

'①受注データを取り込む
'②配列に格納する（シートを選択し、正しいデータか確認。違ったら中断）
'③受注データを保存せずに閉じる
'<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

'ここから①
    Dim 受注データwb As Workbook
    '以下省略
    
End Sub

①、②、③と箇条書きにし、コードの本文にその番号と対応させていきます。デバッグや不具合修正、仕様変更のためのバージョンアップ時の効率が倍増します。

人への連絡

上記はコードの中身を分かりやすく為のメモでした。ここからはコードの中身と関係なく、純粋に周囲や引き継ぎ相手への連絡のためのモノです

連絡先

誰がこのプログラムを作ったか分かるように宣言セクションに書きます。宣言セクションに自己紹介を書くとは冗談みたいですね。

Option Explicit
'>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
'作成者: ゆん
'内線番号：12345
'部署：業務革新課　自動化推進係
'初版リリース：2019/10/1
'<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Sub SampleProgram()
    '以下省略

これで、仕様変更の依頼も安心です。標準モジュールの一番メインの一番上の所に書いておきましょう。あるいは自己紹介とバージョン管理のためだけの標準モジュールが一個あってもいいと思います。これはVBAの場合です。

バージョン管理

エラーの修正や、仕様変更、機能追加ではバージョンを管理します。バージョンを管理しないと、周囲の仲間に配信したときに、皆さんが最新版を使っているかどうか分からなくなってしまうからです。

シートに記録を残す手もありますが、後述の通り、過去のコードを敢えて残しておく方が良い場合があるので、バージョンも同様にコードの中に書く方が良い場合もあります。

バージョンは上述の、自己紹介のすぐ下に書くと良いと思います。

'>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
'バージョン情報
'Ver.1.0.0　2019/10/1 初版
'Ver.1.0.1　2019/10/2 ヘッダ行が変更しても大丈夫なように変更
        '⇒Module:受注取り込み、Procedure　受注メイン
'<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

過去のコードを記録して残す

これは重要です。つい消してしまいます。仕様が変わったときは変更前のコードを残すようにしましょう。元に戻すのも簡単です。

さらに、古いコードを残しておく一番の理由は「業務の変更の記録残すこと」！

上のバージョン更新の例でサンプルコードを示します。バージョン情報を併せてコメントしておくと、Ctrl+Fでコードの場所を簡単に検索することができます。

Sub 受注メイン()
    'Ver.1.0.1　ヘッダ行が変更しても大丈夫なように変更
    'Const ヘッダrw As Long = 2
    
    '>Ver1.0.1変更ここから
    Dim ヘッダrw As Long
    Dim i As Long
    Dim 最終行rw As Long
    
    最終行rw = Cells(Rows.Count, 1).End(xlUp).Row
    For i = 1 To 最終行rw
        If Cells(i, 1) <> "" Then
            ヘッダrw = i
            Exit For
        End If
    Next i
    
 '<Ver1.0.1変更ここまで
    
    '以下省略

リリース後の消すメモ

自分用のメモ（後で消すタイプ）

自分の為だけの処理の説明

当たり前ですが、残して恥ずかしいような誰の役にも立たない落書きは消します。

    '★昼食後、ここから作業再開。目が痛い。。。★

    '★ココの中身、本当に問題ないか検証する★

後で作業再開する場所や、変数が正しく代入されているかどうかを検証するためにStopステートメントを使うときにはこのようなコメントを入れておくと便利です。

私の場合は「★」を入れています。リリース前に全ての★を消す事がリリース前の儀式です。ユーザーテストは万全にテストが終わっているので、ユーザーテスト版と初版の違いはコードの中にコメントアウトされた「★」が残っているかどうかだけです。

こうすることにより、Stopステートメントや恥ずかしいコメントが残らないようにする事ができます。

デバッグでエラーの原因をあぶり出す為に使う

これは、おなじみコメントアウトです。あえてその行を消して結果がどうなるかを確認することで、変数が狙い通りのは鱈期をしているかなどを検証します。

VBA以外の時の注意（私だけかもしれないけど）

これまでの例はすべてVBAの書き方で説明しました。コメントの例に多くの日本語を使いましたが、実は私はVBAでしかコメントアウトに日本語しか使いません。

理由は過去に痛い目似合ったことがあるからです。

Pythonでコメントを書くときに、ステートメントの最後とコメントの間に全角スペースを使ってしまい、エラー理由が分からずに10分以上ハマってしまったことがあるからです。

全角半角のスペースミスは探すのがめちゃくちゃ難しいです。

VBAの時はそのような失敗もエクセル付属のVBEさんが勝手にうまいこと変換してくれるのですが（内部処理はなんと2Byteだそうです）。一方で、VBA以外に日本語をコメントアウト以外で許してくれるプログラミング言語はおそらく無いと思います。

と言うわけで、VBA以外ではコメントであっても半角英数字しか使わない方が良いかもしれません。