リーダブルコード殴り書きメモ#1

190705

（一応やったことをどこかに書いたほうがいいと思って）
（ほとんど箇条書きだ、、、）

1章　理解しやすいコード
読みやすさの基本定理：コードは他の人が最短時間で理解できるように書かなければいけない
追：コードは短くしたほうがいいが、もっと大切なのは、理解するまでにかかる時間を短くすること

第Ⅰ部　表面上の改善
2章　名前に情報を詰め込む
名前をつけるときには、それが変数であっても、関数であっても、クラスであっても、いい名前をつける。
いい名前をつけるときのポイントは以下
・明確な単語を選ぶ
・汎用的な名前を避ける
・抽象的な名前よりも具体的な名前を使う
・接尾辞や接頭辞を使って情報を追加する
・名前の長さを決める
・名前のフォーマットで情報を伝える
1.明確な単語を選ぶ
例えば、”Get"、のような単語は意味がたくさんあるので、”Fetch”や”Download"のように
より具体的で1つに意味が絞られる名前が好ましい
ただし、気取りすぎると分かりにくいので、そこはバランスを取ろう
2.汎用的な名前を避ける
例えば、”tmp”や”retval"という単語は、本当に「一時的な変数保管です」「戻り値です」以外の意味を持たない
変数の目的や値を表す名前をつけよう
例えば、vの2乗の合計値を表す変数なら、”sum_squares"と名付ければ良い
ただし、本当に一時的な保管しか使わないなら、”tmp"を変数名として使うのは良いだろう
同様に、イテレータで使われるi・j・kも、分かりやすのでありではあるが、イテレータが複数あるときはインデックスにもっと明確な名前、説明的な名前を(例えば、”club_i”・”members_i")つけてやるといい
3.抽象的な名前よりも具体的な名前を使う
ふわっとしか理解できなかった
目的や、使う環境を具体的にくっつけてやればいい、という話か
4.名前に情報を追加する
例えば変数に、値に単位をくっつけてやるとか、使ってる文字コードをくっつけるとか、そういうこと
5.名前の長さを決める
「スコープ」が小さければ、多くの情報を詰め込む必要はない(？？理解できず)
長いのは問題ではないが、必要無い情報は消したほうが良い
6.名前のフォーマットで情報を伝える
定数、変数などで大文字やハイフン、アンダーバーの使い方を決めると分かりやすくなるだろう

3章　誤解されない名前
積極的に「他の意味と間違えられることはないだろうか？」と何度も自問自答すること
2章の具体例とtipsが続いている
1.限界値を明確にするときは、名前の前に”min_”と”max_"を使う
2.範囲を指定するときは”first”と”last"を使う（stopは使わない）
3.包含/排他的範囲には”begin”と”end"を使う
4.ブール値の変数名は、頭にis・has・can・shouldなどをつけて分かりやすくすることが多い。また、名前は肯定形にする！
5.ユーザーの期待、先入観に合わせること
6.たくさんの名前を考えて、その中で名前を深く検討して選ぶ

4章　美しさ
コードを読みやすくするための余白・配置・順序には大きく3つの原則がある
・読み手が慣れているパターンと一貫性のあるレイアウトを使う
・似ているコードは似ているように見せる
・関連するコードをまとめてブロックにする
以上の原則を満たすためにできるテクニックが以下
1.改行
適切な改行によって、似た性質のものは同じ位置に来るように整列させると読みやすい
長くなってしまったときは、コメントを1つにまとめられないか、など工夫もできる
2.ヘルパーメソッドの利用
何度も出てくる操作や引数があって読みにくくするなら、一旦それをメソッドにしてしまって隠してしまうのも手
3.縦の線をまっすくにする
整列させたときに、似た性質のものは、同じ列に並ぶようにすると見やすい
4.一貫性と意味のある並びにする
たくさんの変数を定義した際は、重要度や、アルファベット順に並べるなどして、意味のある並び順にすると良い
5.宣言をブロックにまとめる/コードを段落に分割する
ブロックごとにコメントをつけるとなお分かりやすい
同様に、似ている考えをグループにまとめて、他の考えをグループに分けると、視覚的な「踏み石」を提供できる
6.自身のスタイルに一貫性を持たせる
全コードを見たときに、使っているスタイルやデザインが全て同じであるべき

5章　コメントすべきことを知る
1.コメントするべきでは「ない」こと
コードからすぐにわかることはコメントに書かない
当然パッと読んでわからないコメントはやめるべき、具体的に関数の動作を記述するなりすべき
ひどい名前の補完でコメントするくらいなら、まず名前を変えるべき
2.コメントには自分の考えや経験を記録する
改善点があるとか、こういうコードにした理由があるとか、あるなら書こう
他の人には問題点とか知りようがないのだから
何かしら設定した値にもコメントをつけると良い
3.読み手の立場になって考える
質問されそうなことを想像する！！ハマりそうな罠を告知する！！
また、全体像のコメントをつけると良い
4.とりあえずコメントを書く
とりあえずコメントを書く！後から修正・削除するのは簡単

6章　コメントは正確で簡潔に
コメントは領域に対する情報の比率が高くなければいけない
5章のコメントの質を上げるtipsがまとめられている
1.代名詞を避ける
2.歯切れの悪い文章を磨く
3.関数の動作を正確に記述する
4.入出力の実例をコメントに書いておく
5.コードの意図を書く
6.pythonならではだが、与える引数を(引数の名前)=(引数)の形で渡してやると読みやすい
7.情報密度の高い言葉を使う(ただし慣れが必要)

第Ⅱ部　ループとロジックの単純化
7章　制御フローを読みやすくする
条件やループなどの制御フローはそもそも理解しにくい。できるだけ「自然」に書く
1.条件式の引数の並び順
比較で”<“などを使うときは、左に変化するもの(調査対象)、右にあまり変化しないもの(比較対象)をおくとよい
2.if/elseブロックの並び順には優劣がある
・条件は否定形より肯定形
・単純な条件を先に書く
・関心を引く条件や目立つ条件を先に書く
もちろん上の項目は衝突しうるので、そのときは自己判断する
3.三項演算子
基本的にはif/elseを使ったほうがいい。三項演算子はそれによって簡潔になるときにだけ使おう。
4.do/whileループを避ける
do/while ループが変わっているのは、コードブロックを再実行する条件が下にあることにある
コードを2回読むことになるので避けたほうがいい
5.関数から早く返す
よくわからず
6.悪名高きgoto
よくわからず
7.ネストを浅くする
ネスト：恐らく、if{ }で囲まれる領域のこと、{{{{ }}}}は読みにくいよねって感じ
解決法は以下の二つ
・早めに結果を返してネストを削除する
・ループ内部のネストを削除する(ただし、continue？みたいなのを使うらしい。よくわからん)
8.実行の流れをおえるかい？
よくわからず

8章　巨大な式を分割する
コードの塊が巨大なら、飲み込みやすい大きさに分割する。人間は3,4つしかものを同時に考えられない。
コードをのみ込みやすくするための処理や分割の方法は以下
1.説明変数
式を表す、説明する変数を事前に設定してしまえば、その分式を書かずに済む！
2.要約変数
1と似ている。変数が長い、多くなったら、事前にその内容を要約した変数を作ってしまえば良い
3.ド・モルガンの法則を使う
「notを分配してand/orを反転する」、つまり、論理式を読みやすくできる
4.短絡評価の悪用
「頭がいい」コードを書く必要はない
5.例：複雑なロジックと格闘する
より優雅な手法を見つけるよう努力すべきだろう