リーダブルコード〜表面上の改善〜

名前に情報を詰め込む

明確な単語を選ぶ
  • getはあまり明確でない。
    • GetPage(url)ではどこからとってきたのかわからないのでインターネットからとってくるならFetchPageやDownloadPageにする
  • size
    • HeightやNumNodes、MemoryBytesのように具体的にする
  • シソーラスを使ってもっといい名前がないかさがしてみよう
tmpやretvalなどの汎用的な名前を避ける
  • tmp_fileのようにする
  • 一時的な保存でなければtmp自体使用禁止
  • ループイテレータ
    • i、j、kではわかりにくいときがあるので、culb_i、members_i、users_iのようにする
    • もっと簡潔にci、mi、uiでもよい
名前に情報を追加する
  • idのフォーマットが大切ならidでなくhex_idに
  • 単位がミリ秒ならstart_ms
  • その他の例
    • password→palaintext_password(処理を剃る前に暗号化が必要なことがわかる)
    • comment→unescaped_comment(表示するまえにエスケープする必要あり)
    • html→html_utf8
    • data→data_urlenc
  • すべてに追加するのではなくバグになりそうなとこにだけ追加
スコープの大きな変数には長い名前をつける
  • 短い名前はスコープが数行の変数につけるべき
名前のフォーマットで情報を伝える
  • メンバ変数なら末尾にアンダースコアを加えるなど(例：offset_)

誤解されない名前

例：filter()
  • 選択するならselect、除外ならexclude
例：Clip(text, length)
  • 最後からlength文字削除する場合remove、最大length文字切り詰める場合truncate
  • lengthもmax_lengthに
    • バイト数か文字数か単語数かわからないのでmax_charsにするべき
範囲を指定するときはfirstとlastを使う
包含/排他的範囲にはbeginとendを使う(イベントの開始時刻、終了時刻など)
ブール値の名前
  • is、has、can、shouldなどをつけることが多い
ユーザーの期待に合わせる
  • 平均値を取得するメソッド名にgetMeanはよくない
    • getMeanがその場で平均値を計算する実装でコストが高かったとしても、ユーザーはgetMeanを呼び出してしまう
    • computeMeanのほうがよい
    • list.size()もcountSizeやcountElementsのほうがよい

美しさ

本に載ってるコード例を見よ

貫性のある簡潔な改行位置
メソッドを使った整列
縦の線をまっすぐに
一貫性を意味のある並び
  • 例
    • inputフィールドと同じ並び順にする
    • 最重要なものから重要度順
    • アルファベット順
宣言をブロックにまとめる

コメントすべきことを知る

すべきではないこと
  • コードを読んですぐわかることをコメントに書かない
  • 名前がひどければコメントをつけずに名前を変えろ
自分の考えを記録する
  • 例
    • 「このクラスは汚くなってきている。サブクラスResourceNodeを作って整理したほうがいいかもしれない」
  • コードの欠陥にコメントをつける
    • TODO: (あとでてをつける)
    • FIXME: (既知の不具合があるコード)
    • HACK: (あまりキレイじゃない解決策)
    • XXX: (危険！大きな問題がある)
定数にコメントをつける
  • 値を設定した理由などをかく
読み手の立場になって考える
  • コードを読んだ人が「え？」と思うところにコメント
  • ファイルやクラスには全体像のコメントを書く
  • コードブロックに概要を

コメントは正確で簡潔に

代名詞は避ける
関数の動作を正確に記述
入出力のコーナーケースに実例を使う
コードの意図をかく
  • 「listを逆順にイテレートする」ではなく、「値段の高い順に表示する」に