【読書メモ】リーダブルコード その2

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック 前回の続きです。

3章 誤解されない名前

名前が「他の意味と間違えられることはないだろうか？」と何度も自問自答する。

3.1 例：filter()

results = Database.all_objects.filter("year <= 2011")

この results には何が含まれているだろうか？

• year <= 2011 のオブジェクト
• year <= 2011 ではない オブジェクト

どちらかよくわからないのは、filter があいまいな言葉だからだ。

「選択する」のであれば、select() にしたほうがいい。「除外する」のであれば、exclude() にしたほうがいい。

3.2 例：Clip(text, length)

const clip = (text, length) => {
↓↓↓
const truncate = (text, maxChars) => {

上記と同じ考え方で読み手に疑問を抱かせないようにする。
最後から length 文字を削除するなら、remove
最大 length 文字まで切り詰めるなら、truncate

length も

• バイト数
• 文字数
• 単語数

なのかが明確でなく、名前に単位をつけたほうがいいので、maxChars にするとよい。

3.3 限界値を含めるときは min と max を使う

const cartTooBigLimit = 10; //「未満」か「以下」かわかりづらい
↓↓↓
const maxItemsInCart  = 10;  // min や max を使うとわかりやすい

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

const integerRangeStart  = 2;
const integerRangeEnd    = 4; // 終端を範囲に含めるのかが分かりづらい
↓↓↓
const integerRangeStart  = 2;
const integerRangeLast   = 4; // End ではなく Last を使う

3.6 ブール値の名前

let readPassword        = true; // 「これから読み取るか」「すでに読み取っているか」分かりづらい
↓↓↓
let needPassword        = true; // or
let userIsAuthenticated = true; // こちらでもよさそう

ブール値の変数名は、頭に is has can should などをつけてわかりやすくすることが多い。

例：spaceLeft() => hasSpaceLeft()

それから、名前を否定形にするのは避けたほうがいい。例えば、

disableSSL = false;
↓↓↓
useSSL     = true; // 肯定形にしたほうが声に出して読みやすい

3.7 ユーザの期待に合わせる

get() や size() には軽量なメソッドがユーザに期待されている。

4章 美しさ

優れたソースコードは「目に優しい」ものでなければいけない。

• 読み手が慣れているパターンと一貫性のあるレイアウトを使う。
• 似ているコードは似ているように見せる。
• 関連するコードをまとめてブロックにする。

4.4 縦の線をまっすぐにする

列を「整列」させれば、コードが読みやすくなることがある。

整列すべきなのか？

ぼくたちの経験では、プログラマが心配するほどの手間にはならない。もし手間になるようだったら、そのときは止めればいい。

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

const details  = '詳細情報';
const location = '場所';
const phone    = '電話番号';
const email    = 'Eメール';
const url      = 'URL';

であれば、ランダムに並べるのではなく、意味のある順番に並べるといい。例えば、こんな感じだ。

• 対応するHTMLフォームの <input> フィールドと同じ並び順にする。
• 「最重要」なものから重要度順に並べる。
• アルファベット順に並べる。

4.7 コードを「段落」に分割する

文章は複数の段落に分割されている。それは、

• 似ている考えをグループにまとめて、他の考えと分けるためだ。
• 視覚的な「踏み石」を提供できるからだ。これがなければ、ページのなかで自分の場所を見失ってしまう。
• 段落単位で移動できるようになるからだ。

これと同じ理由で、コードも「段落」に分けるべきだ。

const suggestNewFriends = (user, emailPassword) => {
  // ユーザーの友達のメールアドレスを取得する
  ...

  // ユーザーのメールアカウントからすべてのメールアドレスをインポートする。
  ...

  // まだ友達になっていないユーザを探す。
  ...

  // それをページに表示する
  ...
}

4.8 個人的な好みと一貫性

最終的には個人の好みになってしまうこともある。例えば、クラス定義の開き括弧の位置がそうだ。

class Logger {
    ...
};

または、

class Logger
{
    ...
};

どちらを選んだとしても、コードの読みやすさに大きな影響はない。でも、この2つのスタイルを混ぜてしまうと、すごい読みにくいものになってしまう。

一貫性のあるスタイルは「正しい」スタイルよりも大切だ