Robert C. Martin先生のCleanCode第4章を読んだメモ。

コメント(第4章)の概要

  • コメント
    • コメント自体は良いものではない。(必要悪)
    • コードでうまく表現するときに失敗したときに書く。
  • コメントでダメなコードを取り繕うことはできない。
    • コメントを書く前にコードで表現できないかを考える。
  • 自分自身をコードで説明する。
    • (account.accessCount === 0) && echo 'Hello'; よりも (account.firstAccess()) && echo 'Hello'; のようにコードで表現するようにしなさい。
  • 良いコメント
    • まっとうなコメント
      • 著作権表示
      • ライセンスのリンク(ライセンス文章自体は入れない方が良い)
      • ドキュメントへの参照
    • 情報を与えるコメント
      • 複雑な正規表現に対してマッチする参考例など
      • 抽象メソッドの返り値に関する説明(メソッド名で説明できない場合)
    • 意図の説明
      • firebaseでは500件ごとにしかcreateできないので500件ごとに配列を分割する など。
    • 明確化
      • 標準モジュールを利用していて自分でそのコードを改変できない状況の場合などに意図を明確化するために書く。
      • expect(a === b).toBe(true); // a === b など
    • 結果に対する警告
      • このfixtureは大規模なデータが入っている時の検証用のため、開発マシンの容量に余裕があるときに利用してください。 など
    • todoコメント
      • IDEがだいたい教えてくれる。
      • ただし、そのままにせず、検索して積極的に潰すこと。
    • 強調
      • 一見筋の通らないことを強調する目的で使う。
      • searchWord.trim() に対して、前後のスペースを除去しておかないと別のリストとして認識されるなど
    • 公開APIにおけるJavadoc
      • Javadocをきちんとメンテナンスする必要がある。
      • 後述のよくないコメントの点に十分に留意して。
  • よくないコメント
    • ぶつぶつ言う
      • 他のモジュールを調べなければ意味がわからないコメントは、情報伝達に失敗していて記憶領域の無駄
    • 冗長なコメント
      • コードの処理内容を表している。
        • コードを読んだ方が早い
      • Javadocのプロパティの説明(プロパティ名を日本語で表しているだけ)
    • 誤解を招くコメント
      • 正確な内容を表していないコメントのこと。
    • 命令コメント
      • 全ての関数にJavadocを書けのようなルールは悪
      • このゴミには何の付加価値もなく、単にコードをわかりにくくし、潜在的な嘘と間違いを生産している(原文ママ)
    • 日誌コメント
      • N年N月N日 〇〇をした などのコメント
      • バージョン管理システムがないころの過去の遺物
    • ノイズコメント
      • コンストラクタ などのすでに明らかなこと。
      • ちょっと休ませてほしい など筆者の感情のみで何の意味も持たないコメント
        • コメント書くぐらいなら休ませてほしいと思わないコードを書くことに労力を費やすべき
    • 道導
      • // Actions //////////// のようなコメント
      • こういったコードの下にコードを集約させることにほとんど意味がない。
      • なるべく使い過ぎず、注目を集めるという効果が最大限のときに使うべき
    • 閉じ括弧コメント
      • ブロックの最後に、ブロックがどのブロックで終わるのかを表すコメント // endif など
      • ゴミ
      • 必要になるほどネストが深いことが問題。
    • 属性と署名
      • Added by ytetsuroなどのコメント
      • バージョン管理システムでやれ
    • コメントアウトされたコード
      • コード自体をコメントアウトする行為
      • バージョン管理システムでやれ
    • HTMLコメント
      • 読みづらい
      • ツールの問題
    • 非局所的なコメント
      • この関数はAで呼び出されるはずなので デフォルトの値は3 のような使われ方前提で書かれているコメント
        • デフォルトならデフォルト値をメソッドに定義しろ
      • いつクライアントコードが変更されるかなんてわからない
    • 多すぎる情報
      • RFCのリンクと、該当箇所の引用などが記載されているコメント
    • 不明瞭なコメント
      • コメントを読むのに説明が必要なコメント
    • 関数ヘッダ
      • 説明が不要なほど関数を短くしろ
    • 非公開のJavadoc
      • 公開しないならJavadocを書く必要がない。

感じたこと

とにかく、コメントが嫌いなようでこの章では ゴミ という直接的な表現が多く出てきた。
概ね納得だが、PHPやJSのような動的型付け言語ではIDEレベルでdocコメントを見ているのでその点は勘弁してほしいなと思った。(TypeScript や PHP 7.0 < を使えばある程度解決するが。)
冗長なコメントについて、個人的にはプロパティ名に知らない英単語があった場合などは、どのような意味かが調べずともわかると言う点では一概に悪とは言えなさそうだと思った。(メンテナンスされるか？という点に関しては確かに本著の通りだとは思った。)