結局コメントってどんなこと書けばいいのよ?

コメント、書いてますか?

プログラムを書く時、処理に対する解説などの用途としてコメントを書くことがあると思います。
プログラムの勉強をし始めた時などは、まず実装を行う前にどのような処理を行うかをコメントで書いてから実装した方がいい、プログラムと同じくらいコメントもたくさん書こう!等と教えられた方も多いと思います。(筆者もその一人)
実際のところ、コメントはどれくらいの粒度でどれくらいの量記載するのが正しいのでしょうか?
ここではコメントを書くことの意義や有用性、そして実際にどのように書くべきかを考えていきたいと思います。

コメントの例

早速ですが、コメントの例を記載しながら考えていきたいと思います。
サンプルについては僕が実際に仕事や本、その他資料で見たり書いたりしたものを例題用に変更したものですので、必ずしも普遍性が担保されているものではないということについてはご留意ください。
サンプルのコードはphpを使用しますが、他の言語でも同様の考えができるかなと。

/**
 * 数量と単価から合計金額を算出する
 * @param int $quantity 数量
 * @param int $price 単価
 * @return int
 */
public function calculation(int $quantity, int $price): int
{
    // 数量と個数を掛けて合計金額を返す
    return $quantity * $price;
}

関数を説明するための(phpではphpdocなどと呼ばれる)コメント

/**
 * 数量と単価から合計金額を算出する
 * @param int $quantity 数量
 * @param int $price 単価
 * @return int
 */

実際に関数内で何をしているのかを説明している処理に対するコメント

// 数量と個数を掛けて合計金額を返す

関数についてのコメントは単純にそれ自体の説明に加え、IDEなどで解析をする際に有用になったりもしますので、記載することでさまざまなメリットが享受できます。
処理に対するコメントは、ここでは処理自体が簡単なため正直つける意味がないように見えます。
このような例の場合は消してしまってもいいのではないでしょうか。

続いてもう少し複雑な処理が行われている場合の例を見てみましょう。

/**
 * 数量と単価、商品コードから合計金額を算出する
 * @param int $quantity 数量
 * @param int $price 単価
 * @param string $code 商品コード
 * @return int
 */
public function calculation(int $quantity, int $price, string $code): int
{
    $discountRate = 1;

    // 商品コードの先頭がa始まりの場合、合計金額から2割引にする
    if (strpos($code, 'a') === 0) {
        $discountRate = 0.8;
    }

    // 数量が5つ以上の場合は単価を100円引きする
    if ($quantity > 5) {
        $price -= 100;
    }

    return ($quantity * $price) * $discountRate;
}

すこし業務ロジックのような処理が入ってきました。
コメントもそれぞれの業務ロジックらしきところで記載されており、一見良さそうに見えますね。
ただこのコメント、本当に役に立つコメントなのでしょうか?
当然無意味というわけではありません。
今回の例では単純な処理ですが、ロジックが複雑になればなるほど処理の理解の補助となるようなコメントの有用性は上がっていくでしょう。
しかし、例えば自分が突然このコードの修正や追加対応を頼まれた場合のことを考えてみてください。
基本的にプログラムは仕様とセットです。
そのためコードを読んでいるときも、往々にして仕様と照らし合わせながら読み進めていくことになると思います。
このコードを見たとき、数量と単価を掛けて金額を出しているのはわかるけど、この値引きはなんで行われているんだ・・・?と思うのではないでしょうか。

どんな処理をしているのかは難しいロジックでもコードを根気よく追えばある程度はわかりますが、「なぜ」そのロジックが必要なのかはコードを追うだけではそうそうわかりません。
そのため、優先して記載するべきはどうしてそのロジックを行う必要があるのかという「なぜ」の部分と個人的には考えています。
それを踏まえてコメントを書き換えると下記のような例が考えられます。

/**
 * 数量と単価、商品コードから合計金額を算出する
 * @param int $quantity 数量
 * @param int $price 単価
 * @param string $code 商品コード
 * @return int
 */
public function calculation(int $quantity, int $price, string $code): int
{
    $discountRate = 1;

    // 商品コードの先頭がa始まりの場合、アウトレット商品のため2割引する
    if (strpos($code, 'a') === 0) {
        $discountRate = 0.8;
    }

    // 数量が5つ以上の場合はセット割引として単価を100円引きする
    if ($quantity > 5) {
        $price -= 100;
    }

    return ($quantity * $price) * $discountRate;
}

こうすることで多少このコードが何を実現したいがためのコードであるかが理解できるようになったのではないでしょうか。

「何」より「なぜ」を重視したいよねという話

やや極論となってしまうかもしれませんが、どんなに難しいロジックでも「何」をしているかについてはプログラムが記述通りにしか動かないという前提が揺るがない限りはプログラムを読むことで把握できます。
が、「なぜ」についてはプログラムを読むだけでわかることはそうそうありません。
既存のプログラムを読むときは大体大なり小なり事前に把握している仕様が存在し、その仕様とプログラムを照らし合わせることで実現しようとしている仕様はなんなのかというのを紐付けながら読み進めることになるのが多いと思います。
難解なプログラムを読むという前提であっても、「仕様がこうなっているから処理もこうなっている可能性が高いな」というあたりを付けながら読むことによって、理解の速度は大幅に変わるのではないでしょうか。

また、普通に「なぜ」も「何」もコメントに書けば良いのでは?という声もあるかもしれませんが、個人的にはコメントは必要最小限に止めるのが大体の場合ベターとなることが多いと思います。大量に記載したところで読むのが重労働になりがち、かつメンテナンスも大変になり、有用なコメントの純度が別に記載する必要のないコメントによって薄まることが多いからです。

そのため、個人的にはプログラムのコメントを記載する際は「なぜ」を重視した記載を心がけるのが良いのではないかと考えています。

とはいえ何事にも例外はつきもの

プログラム読めばわかるよと言っても、そもそも一緒に作業するチームのメンバーが全員同じレベルであるとは限らないですし、難解な処理にはある程度の処理の説明が必要と感じることもままあるかもしれません。
これと言った最適解がない以上、結局毎度のごとく高度な柔軟性を維持しつつ臨機応変に対応するというのが肝要ですが、最低限自分が記載するコメントは誰に対して、どのようなケースでどのようなメリットを与えるコメントなのかというのは意識できると良いですね。