リーダブルコード

リーダブルコードの自分用アウトプット、行き掛けの駄賃に他の方の役に立てば幸いです。
シンプルにしたかったので、「個人的MVP + 三つ以内のポイントまとめ」が基本構成です。

-- 変更履歴
11/20(土) 第一回投稿第Ⅰ部要約

--

構成

　1章理解しやすいコード
第Ⅰ部表面上の改善
　2章名前に情報を詰め込む
　3章誤解されない名前
　4章美しさ
　5章コメントすべきことを知る
　6章コメントは正確で完結に
第Ⅱ部ループとロジックの単純化

第一章理解しやすいコード

個人的MVP　コードは他の人が最短最速で理解できるように書かなければならない

「他の人」がいないかもしれない。しかし、その「他の人」は数日後の自分かもしれない。

第Ⅰ部

第2章名前に情報を詰め込む

個人的MVP　具体的で、明確な単語を選ぶ

明確な単語を選ぶ

よく使いがちな単語は誤解を生みやすい。

get(どこから？、データベースから、インターネットから？)
stop(あとから再開できるならpauseなどが適切)

適切な単語の発見には、シソーラス(類語辞典)を使うとよい。
一例として、以下が紹介されていた

単語代替案

send deliver, dispatch, announce, distribute, route

find search, extract, locate, recover

start launch, create, begin, open

make create, set up, build, generate, compose, add, new

Dustin Boswell (著), Trevor Foucher (著),「リーダブルコード」 p12

汎用的な名前を避ける(tmp, retval, foo)

tmp, retval, foo: 名前自体に意味を全く持たない。他の関数に渡さない、数行しか使わないという場合はOK。

大文字やアンダースコアに意味を含める

クラスのメンバ変数にアンダースコアをつけて、ローカル変数と区別する
クラスはキャメルケース、#defineの変数は全て大文字はこれに該当しそう

第3章誤解されない名前

個人的MVP　範囲指定の書き方一つで、分かりやすく表現できる

ユースケース、使用する変数名、効果

変数名	ユースケース	効果
min,max	限界値	max,minに限界値が含まれることが明確に
first,last	一般的な範囲指定	終端を範囲に含めることが分かる
begin,end	bool値	慣習

bool値の変数名

is,has,can,shouldをつけると分かりやすい
肯定形の名前が分かりやすい

ex)

# bool disable_ssl = false
  # よりも

# bool use_ssl = true 
  # の方が分かりやすい

暗黙の了解

get(),size()のような関数名は、軽量な処理との認識がある。
getで重い処理をするなら、getMean -> computeMean()のように変更すべき

4章美しさ

個人的MVP
美しくするための原則

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

縦の線をまっすぐにする

CheckFullName("Jake Brown" , "Mr.Jake Brown", "");
CheckFullName("James"      , "Mr.James"     , "");
CheckFullName("Kubota Saki", "Ms.Kubota"    , "");
CheckFullName("Tom"        , ""             , "no data");

コードをブロックに分ける

def suggest_new_friends(user, email_password):
  ## ユーザの友人のメールアドレスを取得
  . 
  . 
  ## ユーザのメールアカウントからすべてのメールアドレスをインポート
  . 
  . 
  ## まだ友達になっていないユーザを探す
  .
  .  
  ## それをページに表示する
  
  return render ("hoge")

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

個人的MVP
コメントを書く作業の分解
1. 頭の中にあるコメントをとにかく書き出す
2. コメントを読んで、改善が必要なものを見つける
3. 改善する
これを繰り返す

章末(pp69-71)が非常に素晴らしくまとまっていました
(コメントすべきでないこと、記録すべき自分の考え、読み手の立場になって考える)

コメントすべきでないこと

コードからすぐに分かること
ひどいコードを補う補助的なコメント、この場合はコードを修正する

記録すべき自分の考え

MVPにあるように、とりあえず書き込んでみてそこから改善を繰り返すとよさそうだ

コードが他のやり方でなく、なぜこうなっているのか
定数の値にまつわる背景

image_quality = 0.72 #0.72のクオリティならユーザが妥協できる

コードの欠陥

記法	典型的な意味
TODO:	後で手を付ける
FIXME:	既知の不具合があるコード
HACK:	あまり綺麗じゃない解決策
XXX:	危険！　大きな問題がある

TODO: 大きな問題
todo: 小さな問題
のようにするのも可

読み手の立場になって考える

ファイルやクラスには「全体像」のコメントを残す
ex)関数の要約、クラスの説明、ソースコードを読んだだけでは得られない情報
コードを読んだ人が「えっ？」となる部分をあらかじめコメントしておく
第4章にあるように、コードブロックごとに分ける

6章コメントは正確で簡潔に

個人的MVP　代名詞(これ、それ)を避ける

代名詞を避ける

　# データをキャッシュに入れる。ただし、先にそのサイズをチェックする。
   #よりも
　
  # データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。
   #の方が分かりやすい。

実例を使って簡潔に説明する

実例を入れてコメントすることで、視覚的に処理が理解しやすい

名前付き引数・コメント

定数だけ出てきても意味が分からないので、コメントや、名前付き引数で補うとよい

hoge.py

# 10の意味が分からない
Connect(10,false)

# 名前付き引数で関数を呼び出す
Connect(timeout = 10, use_encryption):
...

Javaやcの場合、上記のことはできないので以下のようにコメントを使用する

hoge.c

#before
void Connect(int timeout, bool use_encryption):
...

# after
void Connect(/*timeout_ms = */10, /*use_encryption = */ false):
...

第Ⅱ部

順次追加予定

最後に

アウトプットすると定着しますね、美しいコーディングライフを！