LoginSignup
63
57

More than 1 year has passed since last update.

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

Last updated at Posted at 2018-01-19

コメントとはなんなのか

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

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

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

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

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

コードの再翻訳

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

// $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);
63
57
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
63
57