第I部要約 リーダブルコード

リーダブルコード

リーダブルコードの自分用アウトプット、行き掛けの駄賃に他の方の役に立てば幸いです。
シンプルにしたかったので、「個人的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
美しくするための原則

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

縦の線をまっすぐにする

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):
...

第Ⅱ部

• 順次追加予定

最後に

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