新人の頃の悩み「ソースコメントはどこまで書くべきなのか？」に今答えてみる。

前書き

新人の頃、先輩方から「コメントをそこまで細かく書かなくていい。逆に読みにくくなる。」とよく言われていました。
新人だった自分は、そこまで書かないとソースコードが理解できませんでした。
要するに、そこまで細かく書かないと理解できないプログラムを書いていたわけです。
(そのプログラムを改修した後輩の「なんでこんなに読みにくいプログラムを作ったんだあのアホ先輩は!」という横顔はまだ覚えています。本当に申し訳ありませんでした。)

そこで、今私がやっている正しいコメントの書き方を公開します。
これで少しでも新人の方がプログラミングをしやすくなってもらえたら幸いです。

結論 コメントを書く = プログラムの設計をする

コメントはプログラムの説明文ではなく、設計のために書きます。
結果として説明文にもなりますが、メインは設計にあります。
つまり、
×：「実装後にプログラムの意味を分かりやすくするためにコメントを書く」
○：「実装のための設計としてコメントを書く」
ことになります。

私のコメントの書き方は以下の通りです。

　①プログラムの流れをコメントで書く。
　②流れに合わせてプログラムを書く。
　③必要なら流れの修正をする。
　④実装後、ヘッダコメント、その他補足説明がいる場所に追加でコメントを書く。

となります。

エラー回避のための緊急策、勘違いしやすい仕様、複雑な条件分岐などの場合補足のコメントを書きますが、基本は実装前に記述したプログラムの流れのコメント以外は書きません。

具体的にどう書くの?

例：登録ボタンを押したとき、画面データを登録するプログラムを作る場合

①プログラムの流れをコメントで書く。

''' <summary>
''' 登録ボタンクリックイベント
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
Private Sub btnRegist_Click(sender As Object, e As EventArgs) Handles btnRegist.Click
    Try
        '■入力データのチェックを行う

        '■画面データを取得する

        '■取得データをDBに登録する

    Catch ex As Exception
        MsgBox(ex.Message)
    End Try
End Sub

②流れに合わせてプログラムを書く。

''' <summary>
''' 登録ボタンクリックイベント
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
Private Sub btnRegist_Click(sender As Object, e As EventArgs) Handles btnRegist.Click
    Try
        '■入力データのチェックを行う
        If IsErrorInputRegist() = False Then
            Return
        End If

        '■画面データを取得する
        Dim dataRegist As DataTable = GetRegistData()
        If dataRegist Is Nothing Then
            Return
        End If

        '■取得データをDBに登録する
        RegistDB(dataRegist)

    Catch ex As Exception
        MsgBox(ex.Message)
    End Try
End Sub

Private Function IsErrorInputRegist() As Boolean

    '*--------------------------*
    '* なんやかんやのチェック処理 *
    '*--------------------------*

    Return True
End Function

Private Function GetRegistData() As DataTable

    Dim dt As DataTable = Nothing

    '*----------------------------*
    '* なんやかんやのデータ取得処理 *
    '*----------------------------*

    Return dt
End Function

Private Sub RegistDB(ByVal dataRegsit As DataTable)

    '*----------------------------*
    '* なんやかんやのデータ登録処理 *
    '*----------------------------*

End Sub

③必要なら流れの修正をする。
例：登録前にデータの整形が必要だったと気づいた場合

まずはイベント部にコメントを追加

''' <summary>
''' 登録ボタンクリックイベント
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
Private Sub btnRegist_Click(sender As Object, e As EventArgs) Handles btnRegist.Click
    Try
        '■入力データのチェックを行う
        If IsErrorInputRegist() = False Then
            Return
        End If

        '■画面データを取得する
        Dim dataRegist As DataTable = GetRegistData()
        If dataRegist Is Nothing Then
            Return
        End If

        '■取得データを登録用に修正する

        '■取得データをDBに登録する
        RegistDB(dataRegist)

    Catch ex As Exception
        MsgBox(ex.Message)
    End Try
End Sub

続いて実装をする。

''' <summary>
''' 登録ボタンクリックイベント
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
Private Sub btnRegist_Click(sender As Object, e As EventArgs) Handles btnRegist.Click
    Try
        '■入力データのチェックを行う
        If IsErrorInputRegist() = False Then
            Return
        End If

        '■画面データを取得する
        Dim dataRegist As DataTable = GetRegistData()
        If dataRegist Is Nothing Then
            Return
        End If

        '■取得データを登録用に修正する
        FormatDataRegistDB(dataRegist)

        '■取得データをDBに登録する
        RegistDB(dataRegist)

    Catch ex As Exception
        MsgBox(ex.Message)
    End Try
End Sub

Private Function IsErrorInputRegist() As Boolean

    '*--------------------------*
    '* なんやかんやのチェック処理 *
    '*--------------------------*

    Return True
End Function

Private Function GetRegistData() As DataTable

    Dim dt As DataTable = Nothing

    '*----------------------------*
    '* なんやかんやのデータ取得処理 *
    '*----------------------------*

    Return dt
End Function

Private Sub FormatDataRegistDB(ByVal dataRegsit As DataTable)

    '*----------------------------*
    '* なんやかんやのデータ整形処理 *
    '*----------------------------*

End Sub

Private Sub RegistDB(ByVal dataRegsit As DataTable)

    '*----------------------------*
    '* なんやかんやのデータ登録処理 *
    '*----------------------------*

End Sub

④実装後、ヘッダコメント、その他補足説明がいる場所に追加でコメントを書く。

''' <summary>
''' 登録ボタンクリックイベント
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
Private Sub btnRegist_Click(sender As Object, e As EventArgs) Handles btnRegist.Click
    Try
        '■入力データのチェックを行う
        If IsErrorInputRegist() Then
            Return
        End If

        '■画面データを取得する
        Dim dataRegist As DataTable = GetRegistData()
        If dataRegist Is Nothing Then
            '登録データがないときは登録処理終了
            Return
        End If

        '■取得データを登録用に整形する
        FormatDataRegistDB(dataRegist)

        '■取得データをDBに登録する
        RegistDB(dataRegist)

    Catch ex As Exception
        MsgBox(ex.Message)
    End Try
End Sub

''' <summary>
''' 入力データのチェックを行う
''' </summary>
''' <returns>True:エラー有,False:エラーなし</returns>
Private Function IsErrorInputRegist() As Boolean

    '*--------------------------*
    '* なんやかんやのチェック処理 *
    '*--------------------------*

    Return True
End Function

''' <summary>
''' 画面データを取得する
''' </summary>
''' <returns>画面データのDataTable</returns>
Private Function GetRegistData() As DataTable

    Dim dt As DataTable = Nothing

    '*----------------------------*
    '* なんやかんやのデータ取得処理 *
    '*----------------------------*

    Return dt
End Function

''' <summary>
''' 取得データを登録用に整形する
''' </summary>
''' <param name="dataRegsit">登録データ</param>
Private Sub FormatDataRegistDB(ByVal dataRegsit As DataTable)

    '*----------------------------*
    '* なんやかんやのデータ整形処理 *
    '*----------------------------*

End Sub

''' <summary>
''' 取得データをDBに登録する
''' </summary>
''' <param name="dataRegsit">登録データ</param>
Private Sub RegistDB(ByVal dataRegsit As DataTable)

    '*----------------------------*
    '* なんやかんやのデータ登録処理 *
    '*----------------------------*

End Sub

以上になります。