リーダブルコード 輪読会 資料
1章: 理解しやすいコード
鍵となる考え
コードは理解しやすくなければいけない。
コードは他の人が最短時間で理解できるように書かなければならない。
以下、これを「読みやすさの基本的定理」と呼ぶ
「理解」とは、変更を加えたりバグを見つけたり、他のコードと連携する方法が理解できたりと高いハードルのニュアンス
迷ったらこれを最優先に考えるとよい
コードの文字数でなく、理解するまでにかかる時間を減らす
code:sample1.cpp
// better one
bucket = FindBucket(key);
if (bucket !== NULL) assert(!bucket->IsOccupied());
// worse one
assert((!(bucket = FindBucket(key))) || !bucket->ISOccupied());
下のコードが読みづらいのは
スコープが明確でない
脳内にスタックをつまされる
2章: 名前に情報を詰め込む
鍵となる考え
名前に情報を詰め込む。
気取った言い回しより明確で正確なほうがいい。
情報を詰め込んだ名前のつけ方6つ
明確な単語を選ぶ
汎用的な名前を避ける
より具体的な名前を使う
接頭辞や接尾辞を使って情報を追加する
名前の長さを決める
名前のフォーマットで情報を伝える
明確な単語を選ぶ
気をつけたい単語
get, size,send,find,make start/stop
もう一段掘り下げてみる
ex: find->search,extract
「カラフル」な名前を使う
ただし、気取った言い回しよりも明確で正確な名前を使う
汎用的な名前を避ける
気をつけたい単語
tmp,it, retval, i/j/k
変数名が浮かばなくても、変数の目的や値を表す名前をがんばってつける
「この変数は最終的に何になるのか」を言えるなら、名前をつけたほうがいい
スコープが限りなく狭い範囲で一時的に使うならtmpでもいい
code:ts
uesrs.map(u => u.name)
より具体的な名前を使う
いくつかの実例
ServerCanStart() -> CanListenOnPort()
DISALLOW_EVIL_CONSTRUCTORS -> DISALLOW_COPY_AND_ASSIGN
--run_locally -> --extra_logging, --use_local_database
具体的に何が起こっているかを名前に込める
形容詞や副詞をあまり使わず名詞を使う?
接頭辞や接尾辞を使って情報を追加する
知らせなくてはいけない情報を追加する
値の属性を追加する
単位
エスケープの有無
文字コード
URLエンコード
※ハンガリアン記法ではない、型などで知れる情報を入れる必要はない
名前の長さを決める
あまりに長い名前は見づらいが、そこまで忌避する必要はない
エディタの補完機能
頭文字や省略形は広く使われているものなら使う
⭕evaluation -> eval, string -> str
❌BackEndManager -> BEManager
スコープが小さければ短い名前でもいい
名前のフォーマットで情報を伝える
命名でフォーマットを決める言語はいくつかある
CSS(BEM)の__ -
JQueryの$
プライベートクラスの_
Goの大文字小文字
合意が取れているという前提で、一貫性を持たせる
5章: コメントすべきことを知る
鍵となる考え
コメントの目的は、書き手の意図を読み手に知らせることである。
コードからすぐにわかることをコメントに書かない。
コメントすべきでは「ない」ことを知る
コードを読むほうがコメントを読むより理解が早いなら、そのコメントは不要
コメントのためのコメントは不要
関数の名前と引数をそのまま言葉に起こすのは、コメントをするためのコメントになっている
コードの命名を説明するようなコメントは、そもそも元の命名を変える
優れたコード > ひどいコード + 優れたコメント
code:ng.ts
// Replyに対してRequestで記述した制限を課す
const cleanReply = (Request: request, Reply: reply) =>
code:ok.ts
// replyをrequestにある項目数やバイト数の制限に合わせる
const enforceLimitsFromRequest = (Request: request, Reply: reply) =>
コードを書いているときの自分の考えを記録する
「監督のコメンタリー」を入れる
コードの意図、考えを説明する
code:sample.ts
// このデータだとハッシュテーブルよりバイナリツリーの方が40%速かった
// ヒューリスティック
// このクラスは汚くなっている。、サブクラスを作って整理したほうがいいかも
spdbear.iconコミットメッセージで十分かも?カーソル行のコミットメッセージを表示するエディタ拡張など
コードの欠陥にコメントをつける
これからコードをどうしたいかを書く
table:記法
記法 ニュアンス spdbear.icon個人的な用途
TODO: あとで手を付ける 今回のPRではやらないが、リリース前には直される
FIXME: 既知の不具合があるコード リリース後、誰かに直してほしい
HACK: あまりキレイじゃない解決策 使ったことない、NOTE: なら使うかも
XXX: 危険!大きな問題がある 使ったことない
定数にコメントをつける
その値がもつ背景を説明する
code:example.ts
const MAX_RSS_SUBSCRIPTIONS = 1000; // 合理的な限界値
const IMAGE_QUALITY = 0.72; // ユーザがファイルサイズと品質の面で妥協できる値
spdbear.iconNOTE:で書くイメージ、あとは意思決定のIssue, PRリンクを貼るとか
読み手の立場になって何が必要になるかを考える
質問されそうなことを想像する
あまり知られていないテクニック
ハマりそうな罠を告知する
思ったより多い計算量、実行時間
何も知らずに実行するとびっくりしそうなもの
spdbear.iconそもそも命名を変えれば済む話かも
「全体像」のコメント
新しく入ってもらう人に教えるような感覚で
要約コメント
5.1 NG例との違いはどこだろう
WHAT、WHY、HOWに拘らず、役立つものなら何でも
ライターズブロックを乗り越える
ライターズブロックは行き詰まって文章が書けないこと
コードを書いて考えていることをそのまま書く
ヤバい、これはリストに重複があったら面倒なことになる
注意: このコードはリストの重複を処理できません(実装が難しいので)
コメントを書くことは以下の手順から成る
頭の中にあるコメントをとにかく書き出す
コメントを読んで、改善の必要そうなものを見つける
改善する
早めに何度も書くことで、手順1の品質が上がり、
6章: コメントは正確で簡潔に
鍵となる考え
コメントは領域に対する情報の比率が高くなければならない。