xxxさんの備忘録

xxさんのブログです.xxさんはネカマです.

リーダブルコード (第一部)備忘

$1、理解しやすいコード
・読みやすさの基本定理
 ・コードはほかの人が最短時間で理解できるように書く
$2、名前に情報を詰め込む
・明確な単語を選ぶ(気取った言い回しよりも正確。明快さを求める)
ex.get→どこから?わかりにくい。
インターネットからFetchPage、DownloadPageなど
・汎用的な名前を避ける(理由がない場合には避ける)
tmp という名前は、生存期間が短くて、一時的な保管が最も大切な変数にだけ使用
for文iはそれだけでは何を指しているのかわからない場合もあるので場合によってはmember_i等にしてもよい
・抽象的な名前よりも具体的な名前を使う
ex,run_locally→ローカル以外でも使用する可能性などから分かりにくい。-

  • extra_loggingとオプションでlocal_databaseを用意した。

・接尾や接頭を使って情報を追加する
値の単位として(ms,secなどを尾につける)
変数の意味を間違えるとバグが起きそうな箇所にはutf8や
・名前の長さを決める
プロジェクト固有の省略は相手が初見の場合、暗号のように見えるため避けるべき。
・名前のフォーマットを情報で伝える
exクラスのメンバ変数にアンダースコアを付けてローカル変数と区別するなど
$3、誤解されない名前
・名前が他の意味と間違えられることはないかと考慮する
・cf:”filter”→除外するか選択するかわからない。
選択する→select、除外する→exclude
・cf”Clip(text,length)”→"Trucate"もしくはremove切り取りにかえるほうがいい。
length→・バイト数、文字数、単語数 というように様々な解釈ができるため、明確にするべき
・限界値を含めるときはmin,maxを使う
・範囲を指定する時はfirstとlastを使う
・包含/排他的範囲にはbeginとendを使う
・ブール値(boolearn)の名前や値を返す変数はtrue,falseがどうなっているかを明確に分かる形で命名するべき
 また、否定より肯定のほうが明白なことが多い
・ユーザーの期待に合わせる
(get,sizeは軽量なメソッドが期待されいている)
・最善の名前について考えるとき、それらは誤解しない名前を考えることにつながる。
→コードを読む人が意図を正しく理解できるように。
4美しさ
・読み手が慣れているパターンと一貫性のあるパターンを使う
・似ているコードは似ているように見せる
(ex.一貫性のある改行位置など)
・関連するコードはまとめてブロックにする
(ex.読みやすい論理的なグループに分けるなど)
→美しいコードのほうが読むために使う時間が少なくて済む

5コメントすべきことを知る
・コメントすべきではないことを知る
→コードからすぐわかることをコメントに書かない
・ひどい名前はコメントを付けずに名前を変える
→一読しただけでわかるような命名を心掛ける
・自分の考えを記録する
→情報のあるコメント(計算の調査についてなど)
→//TODO:(コードの欠点を記録する)など
→定数にコメントを記録する
・読み手の立場になって考える
プロジェクトを熟知していなくとも読めるコードを目指す。
→質問されそうなことを想像する
・ライターズブロックを乗り越える
→ともかく必要だと思ったことは書いたほうがいい

6コメントは正確に簡潔に
コメントは領域に対する情報比率が高いほうが好ましい
・コメントは簡潔にしておく
・曖昧な代名詞は避ける
・関数の動作を正確に記述する
△入出力のコーナーケースに実例を使う
・コードの意図を書く
→ex 「listを逆順にイテレートする」よりも「値段を高い順に表示する」のほうが
プログラムの動作を高いレベルから説明している
・「名前付き引数」コメント
→よくわからない引数にコメントを付ける
ex.
(/*timeout_ms = */10, /* use_encryption = */ false)
・情報密度の高い言葉を使う
→正規化のようにわかっていて短くできるような言葉がないかを確認する (編集済み)