コメントは書いた方がいい。絶対に。

古い言い伝えに
「汝、一目瞭然なるコードにてコメント残すべからず」
というものがあります。

だいたい2年目くらいのプログラマーが興味を持つ古文書に記されていることから、

適切な変数名や関数名をつけていればコメントなど必要ない。
転じて、コメントを書かなければいけないようなコードは██だ。

のように誤読されている方をたまに見かけます。

書かない方が良いとされるコメント

そこまで極端ではなくとも、書かない方が良いコメントとして以下のような例をよく見ます。

// メールを送信する
メール.送信()

確かにここだけを見れば、同じことが書かれているだけなので不要にも感じます。
しかし、全体の一部として見た場合では見え方が変わってきます。

書かない方が良いとされるコメントでも書いた方が良い理由

まず、適切な変数名・関数名をつけることを心がけるのは大前提として、
それでもコメントを書いた方がよいと考える理由は、視覚的にみやすくなるからです。

シンプルで分かりやすさを求められる変数名・関数名よりも、得意な日本語でコメントを書いた方が確実に伝えやすいというのもありますが、 // のようなお決まりのルールで始まり、さらに文字色が他のコードとは異なるコメントは、コードを読む時に「何かをした場所」として目立ちます。

以下の３つの例は同じコードに異なるコメントの付け方をしたものです。

コメントを書かない

const メール = 新しいメール();

メール.宛先("部長@大企業.jp");
メール.CC(["社長@大企業.jp"]);
メール.送信元("私@大企業.jp");
メール.件名("██████");
メール.HTML("メールテンプレート/██████.html", データ);

const 結果 = メール.送信する();

if (!結果) {
  ログ出力("...");
}

return 結果;

処理自体がシンプルなのでコメントが無くても十分に読みやすいです。

補足と仕様についてのコメントだけを書く

見れば分かりますが、他の直接値を渡している箇所と異なるHTMLメソッドについての補足と、エラー時にはログを出力するという仕様についてのコメントを追加しました。

const メール = 新しいメール();

メール.宛先("部長@大企業.jp");
メール.CC(["社長@大企業.jp"]);
メール.送信元("私@大企業.jp");
メール.件名("██████");

// メール本文を設定する
// メール本文はメールテンプレートとデータを指定して描画する
メール.HTML("メールテンプレート/██████.html", データ);

const 結果 = メール.送信する();

// エラーの場合はログを出力する
if (!結果) {
  ログ出力("...");
}

return 結果;

パッと見た時に、コメントしている箇所が目に留まりやすくなっています。

書かない方が良いとされたコメントも書く

さらに、冒頭のインスタンス生成と、メール送信の箇所にもコメントを追加しました。

// メールインスタンスを生成
const メール = 新しいメール();

メール.宛先("部長@大企業.jp");
メール.CC(["社長@大企業.jp"]);
メール.送信元("私@大企業.jp");
メール.件名("██████");

// メール本文を設定する
// メール本文はメールテンプレートとデータを指定して描画する
メール.HTML("メールテンプレート/██████.html", データ);

// メールを送信
const 結果 = メール.送信する();

// エラーの場合はログを出力する
if (!結果) {
  ログ出力("...");
}

return 結果;

コメントを追加したことで処理の開始箇所とメール送信部分も他のコメント箇所同様に目に留まるようになりました。

デバッグやコードを読む時、「何かをした場所」が見るべきポイントであることが多いはずです。

改めて二つ目の例と見比べてみて、
おそらく何かが起きた時に一番に見るであろうメール送信箇所が圧倒的にみやすくなっています。

まとめ

コードについての説明以外にもコメントを書くメリットはあります。
「書くべきではない」に怯えてコメントが何もないコードになってしまうよりも、コメントは書くをベースにゆっくり自分の経験で判断するのがよいと思います。