リーダブルコード

リーダブルコード

O'REILLY Japan

 

本書のテーマ

読みやすいコードを書くコツを会得しよう!

 

読みやすさの基本定理

コードは他の人または(数カ月後の自分)が最短時間で理解できるように書くべし!

 

表面上の改善

 

Check 鍵となる考え ポイント
名前に情報を詰め込む 明確な単語を選ぶ 汎用的な名前を避ける 抽象的な名前よりも具体的な名前を使う 接尾辞や接頭辞を使って情報を追加する 名前の長さを決める 名前のフォーマットで情報を伝える

 

  • 類語辞典を使って、より明確で正確な単語を探してみるべし

  • tmpという名前は生存期間が短い変数につけるべし

  • イテレータによく使うi, jなどを説明的な工夫を(club_i, members_i, users_i とか)

  • 変数名に単位を入れる (size_mbyte, max_kbps, delay_secとか)

  • 重要な属性を付与する (plaintext_pasword, html_utf8とか)

  • スコープが狭いなら短い変数名もOK

  • プロジェクト固有の省略形はNG

  • 意味が損なわれないなら不要な単語を削除 (ConvertToString→ToString)

  • 名前のフォーマットで情報を伝える

以下はGoogle社のあるプロジェクトチームで使われているフォーマット規約(らしい)

要するに、自分自身やチームで規約を守ろうということ。

クラス名:キャメルケース

ローカル変数:小文字をアンダースコアで区切る

メンバ:最後にアンダースコア

static const int kMaxOpenFiles = 100;
class LogReader {
   public:
   void OpenFile(string local_file);
   private:
   int offset_;
};

 

Check 鍵となる考え
他の意味と間違えられることはないか自問自答すべし
  • 限界値を含めるときはmin, maxを使う

  • 範囲を指定するときはfirst, lastを使う

  • 包含/排他的範囲にはbegin, endを使う

  • ブール値の名前 (is・has・can・shouldなど)

  • ブール変数名は肯定的にすべし

  • ユーザが期待するとおりに命名すべし (get関数は値をgetするだけであるべき)

 

 

Check 鍵となる考え ポイント
そのコードの見た目は美しいか 読み手がなれているパターンか? 一貫性のあるレイアウトか? 似ているコードは似ているように見せる 関連するコードをブロック化

見た目が美しいコードのほうが理解する時間は短縮される!

さっと流し読みできるのが理想。

  • 一貫性のある簡潔な改行位置 (すっと内容が目に飛び込んでくるか)

  • 縦の線をまっすぐにすると文章に目を通しやすくなる

  • 一貫性と意味のある並び

  • 改行で論理的なグループに分ける、段落に分ける

  • 一貫性のあるスタイルを貫く

  • マクロを使うとキレイになることがある

  • コードを見て本質がすぐに分かるのが理想

     

 

Check 鍵となる考え ポイント
コメントは書き手の意図を伝えること コメントすべきでないもの コードを書いている時に自分の考えを記録する 読み手の立場で必要な情報を書く
  • コードから分かることをコメントにしない

  • ひどい名前はコメントをつけず名前を改善

  • 関数名は自己文書化されいろんなところで使われるのでコメントより名前のほうが重要!

  • コメンタリーを入れる (コードが汚い理由を書いたっていい)

  • キーワードでコードの状態を知らせる(以下は一例)

記法 意味
TODO: あとで手を付ける
FIXME: 既知の不具合があるコード
HACK: あまりキレイじゃない解決策
XXX: 危険!大きな問題がある!
NOTE: 注意
  • 定数にコメントをつける (値の根拠などについて書いておこう)

  • 質問されそうなことを先回りしてコメントする

    • 他の人がコードをみてビックリしそうなことを想像する

    • 他の人がどんなふうに間違えて使う可能性があるか想像する

  • 全体像のコメント

  • 要約コメント

  • ライターズ・ブロックを乗り越える(コメントは悪しき習慣の思想)

 

 

Check 鍵となる考え
コメントは明確で正確に詳細に
  • コメントは画面を多くとるし、読むのが億劫になる。そうなると書く意味がなくなる。

  • あいまいな代名詞は避けるべし

  • 歯切れの悪い文章を磨く

  • プログラムの動作を高次元から説明する

  • 名前付き引数コメントを利用 (Connect(/*timeout_ms = */10)とか) ※インラインコメント

  • 情報密度の高い単語を使って文章を簡潔にする

 

 

ループとロジックの単純化

 

Check 鍵となる考え
制御フローは自然にする
3項演算子は記述が簡潔になるときだけに
do - whileを避ける
関数から早く返す(ガード節)、ネストを浅く
巨大な式は、説明変数や要約変数をうまく使って飲み込み安い大きさに分割し コードの主要な概念を認識
  • 条件式の引数の並びに気を配る

    while(byte_expected > bytes_received)
    よりも
    while(bytes_received < bytes_expected)
    のほうが読みやすい
    左辺 右辺
    調査対象。変化する。 比較対象。あまり変化しない。

     

  • 条件は否定形よりも肯定形を使う(ド・モルガンの法則を活用する)

    if(!debug)
    よりも
    if(debug)
    のほうが読みやすい

 

  • 頭の良いコードに気をつける(あとでわかりにくいことがよくある)

 

 

Check 鍵となる考え
変数を少なくし、変数を追跡しやすくする
変数の生存期間を短くする
変数が頻繁に変更されると現在の値を把握するのが難しくなる
  • 役に立たない一時変数を削除しよう

  • 中間結果を削除してみる

  • 制御フロー変数を削除する(ループから抜けるためだけのフラグとか)

  • 変数の定義を使う直前にできないか検討する