読者です 読者をやめる 読者になる 読者になる

by shigemk2

当面は技術的なことしか書かない

リーダブルコード 5 コメントすべきことを知る

読書ノート

前回
リーダブルコード 4 美しさ - by shigemk2

コメントすべきでないこと

  • コードからすぐ抽出できること(「ここはコンストラクタ」とか、組み込みメソッドの意味とか)
  • ひどいコードを補う「補助的なコメント」

記録すべき自分の考え

  • なぜコードが他のやりかたではなくこうなっているのか
  • コードの欠陥をTODO:やFIX:などの記法を使って記す
  • 定数の値にまつわる[背景」

読み手の立場になって考える

  • コードを読んだ人が「え?」となるところを予想してコメントをつける
  • 平均的な読み手が驚くような動作は文書化する
  • ファイルやクラスには全体像のコメントを書く
  • 読み手が細部に囚われないように、コードブロックにコメントをつけて概要をまとめる

優れたコード > ひどいコード + 優れたコメント

正に護身開眼なのである。
本当に優れたコードはコメントの必要すらない。

コードのコメントについて - by shigemk2
コメントにはなぜを書くべきと
よく言われるが、必要ならば、WHATHOWも追加すべきである。