プログラミング
コメント
プログラミング全般
コメント書き方

コードのコメントに書くべき内容・書いてはいけない内容

前提

リーダブルコードの内容くらいは把握していて、実践できてる前提で。

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

一言でまとめると、「書いてしまうと、二重管理になるもの」

二重管理は悪であるなので、そのようなコメントも悪です。

その否定と考えれば、「コメントに書くべきもの」とは、他のなにかで管理できない情報だとわかります。

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

書いてはいけないものとは何かを挙げ、例を示し、なぜ書いてはいけないのか(=なにを見ればわかるのか)をあげます。

コードの再翻訳

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

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

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

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

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

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

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

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

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

コミットメッセージを見ればわかるので、書いてはいけません。
コミットメッセージではなく、Pull Request とかにかかれていることもあります。

@link でチケットのリンクが書かれていたりすることもあるようですが、まぁこれは必要に応じてって感じです。必須にするのはやめておいたほうがいいですよ。

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

README.md やドキュメントに書いたほうが便利なので、そっちを使いましょう。

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

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

コメントに書くべきもの

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

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

例えば、以下の様なやつです。そもそもコードにできないので、どうしようもありません。

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

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

「なぜ、~ないのか」

「普通に考えたら、ここあるべき処理」がなかったりしますね。そういう場合、それが実装漏れとかでなく意図どおりであるということを明記したほうが良いです。

$database = new Database();
// 必要になったときに、各 Controller で `connect()` する

コードブロックの目的

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

例えば以下のコード、コメントなくて理解できるのでしょうか。
(わかりやすい関数名をつけておけばわかるのかな…、フィボナッチ数列の一般項を知ってる人なんてなかなかいないと思うけど。)

<?php
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);