はじめに

まずは下のソースコードを見てください。

const a = 25;
const b = 20;

if (a >= 18 && b >= 16) {
    return true;
} else {
    return false;
}

これ、何の処理かわかりますか？
もしかしたらなんとなく気づいた人もいるかもしれませんね。
今回はこのソースコードをベースにコメントの必要性について考えていきたいと思います。

ソースをリファクタリングしてみる

Step1. コメントを書いてみた

// 男性の年齢
const a = 25;
// 女性の年齢
const b = 20;

// 結婚可否判定
if (a >= 18 && b >= 16) {
    return true;
} else {
    return false;
}

はい、これで何の処理かわかりましたね！正解は「男女２人が結婚可能かどうか判定する処理」でした。コメントなくても勘の良い人は気づいたかもしれませんが、答えがない以上確信は持てなかったはずです。コメントを書くことによって処理の内容が明瞭化され、何をやっているか、何がやりたいかが一目瞭然になったかと思います。これがコメントの最大のメリットです。

「じゃあ、コメントは書くで決まりってこと？」

いいえ、コメントを書かずともソースコードをわかりやすくすることも出来ます。
次はコメントを書かずにソースコードをわかりやすくしたいと思います。

Step2. コメントは書かずに変数名をわかりやすくしてみた

const ageMale = 25;
const ageFemale = 20;

if (ageMale >= 18 && ageFemale >= 16) {
    return true;
} else {
    return false;
}

はい、どうでしょう。これだと一番最初のソースコードよりかは何をやりたいのかがわかりやすくなったのではないでしょうか？でもこれだと結局どんな処理か確信は持てませんよね。「結婚」ってワードは出てきてないし。なのでもう少し手心を加えていきたいと思います。

Step3. 結婚可能年齢を定数にしてみた

const CAN_MARRY_AGE_MALE = 18;
const CAN_MARRY_AGE_FEMALE = 16;

const ageMale = 25;
const ageFemale = 20;

if (ageMale >= CAN_MARRY_AGE_MALE && ageFemale >= CAN_MARRY_AGE_FEMALE) {
    return true;
} else {
    return false;
}

さぁさぁ、これなら誰が見てもコメント無しで正解にたどり着ける気がしませんか？でもif文の条件式がちょっと長いですね。これが何を判定しているかさらにわかりやすくしてみますか。

Step4. 条件式も変数に入れてみた

const CAN_MARRY_AGE_MALE = 18;
const CAN_MARRY_AGE_FEMALE = 16;

const ageMale = 25;
const ageFemale = 20;

const canMarry = ageMale >= CAN_MARRY_AGE_MALE && ageFemale >= CAN_MARRY_AGE_FEMALE;

if (canMarry) {
    return true;
} else {
    return false;
}

なんということでしょう。これならそれぞれの変数が何を表しているかもわかるし、if文が何を判定しているかもわかるようになったと思います。これを見れば誰でも正解にたどり着けるはずですね。ということで、

結論？

ソースコードをわかりやすく書けば、コメントは不要なのであーる

やっと長い戦いに決着をつける事ができました。めでたし、めでたし。
では、さいごにわかりやすさを意識したこのコードを見てみてください。

const NEED_EXTRA_EXPLAIN_AGE = 65;
const MAIN_CUSTOMER_INDEX = 0;

const customersAge = [70, 25];

const isOverAge = customersAge[MAIN_CUSTOMER_INDEX] >= NEED_EXTRA_EXPLAIN_AGE;
const isOnePerson = customersAge.length === 1;
const isNeedExtraExplain = isOverAge && isOnePerson;

if (isNeedExtraExplain) {
    return true;
} else {
    return false;
}

なにをしたいかわかりましたか？おそらくこのソースコードを見て何をしたいかわかる方はほとんどいないと思います。
これは「申込者に補足説明が必要か判定する処理」になります。

仕様は、

• 65歳以上であれば補足説明が必要
• 同行者に65歳未満の方が同席していれば補足説明は不要

になります。

あらためて考える

結婚可否判定のソースコードがコメントなしでもわかるようになったのは、前提知識としてソースを読む人が結婚可否を判定するための仕様（男性は18歳以上、女性は16歳以上）を理解していたからだということがわかりました。なのでいきなり出てきた訳のわからない仕様のソースコードはたとえ同じようにわかりやすく書かれたソースコードでもわからなかったんです。

あらためて結論

ここまで来て最初の２択に迫られます

ソースコードにコメントは必要ですか？不要ですか？

僕の結論は「 不要 」です。今回のケースを見ればわかるかと思いますが、仕様を理解していればソースコードは読めます。なので必要なのはコメントではなく仕様の理解だと思います。仕様は理解したがソースコードが汚すぎて読めない。にも関わらずリファクタリングをする工数も貰えない、規約でコメントを書くことが求められているといったケースではコメントも必要になって来ますが、そうではない場合、僕はコメントを書かないと結論付けました。

さいごに

みなさんの考えはどうですか？おそらく置かれている環境によってコメントの必要性は変わってくると思います。僕は不要と結論づけましたが、別にコメント否定派ではないです。全然あっても良いんじゃないでしょうか。実際コメントに助けられたこともありますし。騙されたこともあるけど。

結局自分がどっちの意見だろうが、なぜそう思ったかが自分の中にあれば良いように思います。周りには自分より優秀な人がたくさんいますが、みんなそういう自分の意見を持っていて、なぜその考えに至ったかを持ってるんですよね。なのでそういう人の真似をして僕も自分の意見と、その考えに至った経緯を持つようにしています。

ではでは