Clean Code ch5 Formatting

Clean Code勉強メモ

出典: 

Formatting

The Purpose of Formatting

  • コードフォーマッティングは(読み手との)コミュニケーション
  • コミュニケーションがプロ開発者の第一級任務
  • 「動かすのが最優先」というのは大間違い
  • 今日実装する機能は、次のリリース時の変更箇所になるかもしれない

    • 可読性が響く
  • 書いたコード自体が新陳代謝で無くなっても、スタイルや規律は残る

Vertical Formatting

  • ファイルの長さ
  • 短いほうが理解しやすい
  • 有名なプロジェクトで統計を取ると、だいたい200行くらい

    • 多くて500行くらい

The Newspaper Metaphor

  • よくできた新聞のようなソースコードを目指す

    • 上の方だけ見て、読むべき記事かどうか判断できる
  • ソースコードで言うと

    • 説明的な名前がついている
    • 一番上の部分を読めば、高水準の概念やアルゴリズムがわかる
    • 下の方へ読み進めるにつれ、低水準の詳細がわかる
  • 新聞は小さな記事で構成させているから読める

    • 巨大な一枚岩だったら読めない

Vertical Openness Between Concepts

  • 異なる概念の間には空行を空けよう

    • import
    • クラス定義
    • 関数定義

Vertical Density

  • 概念的に近いものは空行を空けずに詰める

    • 関連深いインタンスメンバ変数とか

Vertical Distance

  • 概念的に近いものは上下近くに置きたい

    • 別ファイルだと明らかに無理

      • protectedメンバ変数を避けるべき理由の一つ

Variable Declarations

  • 変数宣言はなるべく利用箇所の近くで

Instance Variables

  • これはクラス宣言の上部で行え

    • 設計がまともならクラス中のあちこちで利用されるので、「利用箇所の近く」というのがない
  • C++は最下部だったりする

    • scissors rule
  • よく知られた一箇所にまとまっていることが肝要

Dependent Functions

  • メソッドがメソッドを呼び出す場合…

    • 上のメソッドが下のものを呼ぶように置く
    • なるべく近くに置く
  • 上から下の方向に自然に読めるようになる
  • 【補】下に読み進めるにつれ、低水準の詳細になっていく

    • Newspaper Metaphorに従っている

Conceptual Affinity

  • 同名のオーバライド関数とかは近くに置こう

    • 互いに呼び出すか否かなどは二の次
    • 同じ名前で同じことをするので近くに置く

Vertical Ordering

  • 呼び出し先関数は呼び出し元よりも下にいてほしい

    • 上から下に読みたいから

Horizontal Formatting

  • 行は短いほうがよい

    • 有名なプロジェクトで統計を取ると、長い行の出現頻度は指数関数的に減っていく
  • モニタも大きくなってきているし一概には言えないが、ボブおじ的には120文字くらいが限度

Horizontal Openness and Density

  • 結びつきの弱いものはスペースで区切る
  • 結びつきの強いものは区切らない
return b*b - 4*a*c;
  • 演算子の優先度に基づいて、掛け算のオペランドは区切らず、引き算のオペランドは区切っている
  • 自動フォーマッティングツールでは失われがち
  • 【所感】ことさらに区別したいならカッコ使ったほうが良くない?

Horizontal Alignment

private   int   width;
private   int   height
protected Color backgroundColor;
...
width          = 10;
height         = 20;
backgrounColor = Color.fromRGB(255, 0, 0);
  • このテのフォーマッティング
  • 著者は昔取り入れていたが、やめた

    • 意図がぼける

      • 代入が見えなくなる
      • 右辺を一覧したいわけではない
    • 自動フォーマッティングで消えてしまう
    • 揃っていないのが悪なのではなく、揃えたくなるくらい変数宣言リストが長すぎるのが悪

      • 分割して短くすべき

Indentation

  • (当然すぎるので省略)
  • 「1行だから改行・インデントいらないや」は結局あとで直すことになるのでやめとけ

    • 【所感】自動フォーマッティングに委ねるべきでは

Dummy Scopes

while (dis.read(buf, 0, readBufferSize) != -1);
  • やめよう

    • 末尾の;に騙される

Team Rules

  • たとえ気に入らなくてもチームのルールに従え
  • 最も避けるべきは、個々人のスタイルのごちゃまぜでコードが複雑化すること

    • 【補】APoSDの「複雑性」の定義に合致

      • 認知の負荷

英語

  • disabuse

    • 誤りを気づかせる
  • precedents

    • 先例
  • broad-brush

    • 大まかな
  • as an aside

    • ちなみに
  • pertain

    • に属する
  • the last thing …

    • 最もしそうにないこと
  • jumble

    • ごちゃまぜ