コードのコメントには何を書くのか

コメントとはなんなのか

コメントは「読みやすいコードを書くための手段の一つ」です。
「適切な変数名をつける」とか「一連の処理ごとにコードブロックを分ける」とかはやるのが当たり前で、それだけでは表現できないものを、コメントに書きます。

悪いコメントとは「書くと二重管理になるもの」

二重管理は悪です。
逆に「他のなにかで管理できないものをコメントで書く」ということができていれば及第点だと思います。

コメントに書いてはいけないものの例

書いてはいけないものとは何かを挙げ、なぜ書いてはいけないのか（=なにを見ればわかるのか）をあげます。

コードの再翻訳

「書いてはいけないコメント」の例として、最もよく見るものです。
当然、コードを見ればわかるので、書いてはいけません。

// $aと$bが同一だったら
if ($a === $b) {
}

// idの配列
$ids = [1,2,4,5];

「誰が、そのコードを書いたか」

コミットログを見ればわかるので、書いてはいけません。
バージョン管理システムの blame とかを見ましょう。

「いつ、そのコードを書いたか」

コミットログを見ればわかるので、書いてはいけません。
バージョン管理システムの blame とかを見ましょう。

超絶レガシーなコードだと、「 // 2018-01-19 09:05 DBに保存する処理を追加 」とかいうのも見ますね。

そのクラスや関数の「使い方」

README.md やドキュメントに書いたほうが便利なので、そっちを使いましょう。
そのクラスや関数の Doc コメントに書きましょう。（/** */ で書くアレ）
IDE では関数を使うときに表示されますし、ドキュメントを自動生成するときにも拾われるので、使う側から参照しやすい。

入力に対して、期待する具体的な出力

単体テストとかに書きましょう。

ただし、「例えば ID123456 のような文字列」みたいなものは、書くだけでわかりやすくなるので、Doc コメントには書いたほうが良いです。

コメントに書くべきもの

「コメントに書くべきもの」とは、他のなにかで管理できない情報です。

「1行もコードがない・なにもしない ということ」

例えば、以下の様なやつ。そもそもコードにできないので、コメントに書くしかありません。

try {
    $this->close();
} catch (\Throwable $e) {
    // do nothing
}

bash スクリプトとかだと : っていう「（事実上）なにもしない」命令があったりしますので、そういうときはそっちを使いましょう。

「なぜ、～ないのか」

「普通に考えたら、ここあるべきだと考えられる（かもしれない）処理」を、あえて書いていないんだということは、明記しましょう。

class Database {
  public __constructor() {
    // 「コネクションを張る」ことの成否は外部要因なので、
    //   コンストラクタ内ではコネクションを張らない
    // コンストラクタの処理で、成功したり失敗したりしてほしくない。
  }
  public connect() {}
}

コードブロックの目的

数行に渡っている一連の処理の目的は、コメントに書きましょう。コードをを読む人の手助けになります。

// ゲームのタイトル一覧を取得
$rawData = $client->get('/games');
$gameTitles = array_column($rawData, 'title');

難しい前提知識の説明

普通は知らないであろう知識を要求する場合は、その知識を得られる場所をコメントで明記しましょう。
例えば、以下のコードをコメントなしで理解するのは、とても難しいはずです。

define('GOLDEN_RATIO', (1 + sqrt(5)) / 2);

/** @var int 第n項 */
$n = input()[1];

// フィボナッチ数列の一般項の式を用いて求める
// see https://ja.wikipedia.org/wiki/%E3%83%95%E3%82%A3%E3%83%9C%E3%83%8A%E3%83%83%E3%83%81%E6%95%B0#%E4%B8%80%E8%88%AC%E9%A0%85
$lucasNumber = (GOLDEN_RATIO ** $n) - ((-GOLDEN_RATIO) ** (-$n)); 
$resultRaw = $lucasNumber / sqrt(5);

return floor($resultRaw);