はじめに

「リーダブルコード」とは、他人が読んでも短時間で理解できるコードを書くために必要な知識・テクニックが言語問わず記された本のことです。
エンジニアが読むべき本は何か？と質問すれば、半分の人はオススメぐらいエンジニア界隈では有名な本です。
その「リーダブルコード」を読んで重要だと感じたことを記録します。
また、今後重要だと思ったことも追記していこうと思います。

１.理解しやすいコード

読みやすさで重要な考え方は？？
→他人が最短時間で理解できるように書く

短ければ良いではなく、長くなっても「理解するまでの時間」を天秤にかけることが大事。

２.名前に情報を詰め込む

気をつけること

・明確な単語を選ぶ

Size…物理的な大きさを返すメソッドなのか、量の多さなのか、メモリのことなのか？？
様々な解釈ができる単語を使用すると、読み手が迷ってしまう。。

Point!

・volume,Height,MemoryBytes等の明確にわかる単語を使うことが大事！

　→シソーラス類義語で単語を検索すると良い!

https://www.thesaurus.com/

・汎用的な単語・インデックス文字を使用する場合は、
　意味が一意になるようにする

例）tmp,retval,foo

Point!

インデックスで使用されるi・j・kについて、１つの処理で複数使われてしまう場合は、説明的な名前にする。
(例：user_i,member_i,clubs_i)

・名前に情報を追加する

名前をつけるにあたって、知らせた方が情報がある場合はその「単語」を名前に盛り込む。
(例：start_ms …ミリ秒まで返すことがわかる！)

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

クラス名はCamelCase（キャメルケース🐪）
変数名はlower_separated（スネークケース🐍）

３.誤解されない名前

名前が「他の意味と間違えられないか？」を考える。

・filter()

resulet = Database.all_object.filter("year <= 2011")

問題
2011年を境にフィルターをかけていることはわかるが、2011年を"含む"のか"含まないのか"わかりずらい。

Point!

「選択」するのであれば、select()
「除外」するのであれば、exclude()　を命名する。

・限界値を含めるときは"min","max"を使う

CART_TOO_BIG_LIMIT = 10
if shopping_cart.num_items() >= CART_TOO_BIG_LIMIT:
 Error("カートにある商品が多すぎます")

問題
判定で使用しているCART_TOO_BIG_LIMITが、「１０未満」なのか「１０以下」なのかわかりずらい。

Point!

10を含む場合は、名前の前にmax_やmin_をつける。
例）MAX_ITEMS_IN_CART

・範囲を指定するとき

・数値等の場合→first,last
・日付等の場合→begin,end

・ブール値(true,false)の名前

bool read_password = true;

問題
上記コードだと２つの解釈ができる
・パスワードをこれから読み取る必要がある(true:読み取る必要あり/false:読み取る必要なし)
・パスワードをすでに読み取っている(true:読み取れている/false:読み取れていない)

Point!

・パスワードをこれから読み取る必要がある→ 例）need_password
・パスワードをすでに読み取っている→ 例）user_is_authenticated

４.美しさ

気をつけること

・既存のコードに合わせたシルエット・記述方法を意識する。

・「=」や「名前」等のインデントを揃える

・ある場所でA・B・Cのように並んでいたものを、他の場所でB・C・Aのように順番を変えてはいけない

・空行を使って、大きなブロック・まとまりを論理的な「段落」にわける

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

コメントの基準→コードからすぐにわかることをコメントには書かない！

コメントすべきこと

・自分の考えを記録する(true,false)の名前

なぜこのようなコードになったのか、通常と違う実装をしている場合はコメントをする

・コードの欠陥にコメントをする

よく使われる記法

・定数にコメントをつける

なぜその値なのか、背景をコメントに残す。

・関数等の処理の塊に対して要約コメントをする

パッと見では理解しづらい処理に対して、コメントでどのような処理かの記載があれば読みやすさが全然違う。

６.コメントは正確で簡潔に

以下のことを注意する

・複数の意味を持ってしまう代名詞は避ける

悪い例
// データをキャッシュに入れる。ただし、先にそのサイズをチェックする。

問題
「その」が指しているものがデータなのか、キャッシュなのかあいまいになっている。

Point!

「その」等のあいまいな表現に対して、名詞を代入する！

良い例
// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。

・歯切れの良い文章にする

悪い例
// データチェックしたかどうかで、データを使用するか決める

問題
「したかどうか」では通じるが、パッと見歯切れはよくない

Point!

単純、短い、直接的を意識する！

良い例
// データチェック済みのデータを使用する。

7.制御フローを読みやすくする

・条件式の引数の並び順

左側：「調査対象の式」、変化する。
右側：「比較対象の式」、あまり変化しない。

//例
if (length >= 10)

・if/else ブロックの並び順

なるべく肯定系を使う
単純な条件を先に書く
関心を引く条件や目立つ条件を先に書く

8.変数と読みやすさ

以下の原因によって、コードが読みづらくなる
・変数を適当に使うとプログラムが理解しにくくなる
・変数が多いと追跡が難しくなる
・スコープが大きいと、スコープを把握する時間が長くなる
・頻繁に変更されると現在ではの値を把握するのが難しくなる

改善策

・邪魔な変数を削除する
・中間結果などは不要
・できるだけ小さいスコープとする
・変数のことがみえる行数を減らす
・1度だけ書きこむ変数を使う

終わりに

現段階で、自分が理解できる内容にいついてまとめてみました。
今後業務経験を積むことで、理解できる内容が増えていけば追記していきたいと思います。
ただ、現時点でもかなりの量があり現場特有のルールを加えるとパンクしてしまう気がします。
セルフチェックシートたるものを作成し、忘れがちなポイントを抑えようと思います。