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

# リーダブルコード

[リーダブルコード](https://www.amazon.co.jp/%E3%83%AA%E3%83%BC%E3%83%80%E3%83%96%E3%83%AB%E3%82%B3%E3%83%BC%E3%83%89-%E2%80%95%E3%82%88%E3%82%8A%E8%89%AF%E3%81%84%E3%82%B3%E3%83%BC%E3%83%89%E3%82%92%E6%9B%B8%E3%81%8F%E3%81%9F%E3%82%81%E3%81%AE%E3%82%B7%E3%83%B3%E3%83%97%E3%83%AB%E3%81%A7%E5%AE%9F%E8%B7%B5%E7%9A%84%E3%81%AA%E3%83%86%E3%82%AF%E3%83%8B%E3%83%83%E3%82%AF-Theory-practice-Boswell/dp/4873115655)の自分用アウトプット、行き掛けの駄賃に他の方の役に立てば幸いです。
シンプルにしたかったので、「個人的MVP + 三つ以内のポイントまとめ」が基本構成です。


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

--

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


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

:::note 
**個人的MVP**　**コードは他の人が最短最速で理解できるように書かなければならない**
:::
「他の人」がいないかもしれない。しかし、その「他の人」は**数日後の自分**かもしれない。

# 第Ⅰ部
## 第2章 名前に情報を詰め込む
:::note
**個人的MVP**　**具体的で、明確な単語を選ぶ**
:::

### 明確な単語を選ぶ
よく使いがちな単語は誤解を生みやすい。
- get(どこから？、データベースから、インターネットから？)
- stop(あとから再開できるならpauseなどが適切)


適切な単語の発見には、[シソーラス(類語辞典)](https://dictionary.cambridge.org/ja/thesaurus/)を使うとよい。
一例として、以下が紹介されていた

>|単語|代替案|
>|--|--|
>|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章 誤解されない名前
:::note
**個人的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章 美しさ
:::note
**個人的MVP
美しくするための原則**
1. 読み手が慣れているパターンと**一貫性**のあるレイアウトを使う
2. **似ているコードは似ているように見せる**
3. 関連するコードをまとめてブロックにする
:::

### 縦の線をまっすぐにする
```cpp
CheckFullName("Jake Brown" , "Mr.Jake Brown", "");
CheckFullName("James"      , "Mr.James"     , "");
CheckFullName("Kubota Saki", "Ms.Kubota"    , "");
CheckFullName("Tom"        , ""             , "no data");

```

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

```

## 5章 コメントすべきことを知る
:::note
**個人的MVP** 
コメントを書く作業の分解
**1. 頭の中にあるコメントをとにかく書き出す**
2. コメントを読んで、改善が必要なものを見つける
3. 改善する
**これを繰り返す**
:::
章末(pp69-71)が非常に素晴らしくまとまっていました
(コメントすべきでないこと、記録すべき自分の考え、読み手の立場になって考える)

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

### 記録すべき自分の考え
MVPにあるように、とりあえず書き込んでみてそこから改善を繰り返すとよさそうだ
- コードが他のやり方でなく、なぜこうなっているのか
- 定数の値にまつわる背景
```py
image_quality = 0.72 #0.72のクオリティならユーザが妥協できる
```
- **コードの欠陥**

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

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

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

## 6章 コメントは正確で簡潔に
:::note
**個人的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):
...

```

# 第Ⅱ部
- 順次追加予定

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