リーダブルコードを読んだ際のメモ

概要

リーダブルコードを読んだので、有用だと思った知見をほぼ自分用にメモとして残しておく。自分は研究時代から考えると６年コードを書いているので割と自分もそうしてるな〜と思うところが多かったが、メモしておいても良さそうなものを書き残す。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

２章 名前に情報を詰め込む

ループイテレーター

↓ みたいな感じのコードはよく見るが、これだと間違った参照 (ex. members[j]) が起こり得る。

for i in len(members):
    for j in len(clubs):
        print(f'{members[i]} / {clubs[j]}')

これは ↓ みたいな感じで index に意味をもたせることでリスク軽減可能

for member_i in range(len(members)):
    for club_i in range(len(clubs)):
        print(f'{members[member_i]} / {clubs[club_i]}')

長ったらしいなら ↓ も良い。

for mi in range(len(members)):
    for ci in range(len(clubs)):
        print(f'{members[mi]} / {clubs[ci]}')

変数の命名長

結論、その変数が表す概念をその変数が関わるスコープで表すのに十分かつ最小な長さまで伸ばせば良い。長い命名 != 悪。必要なら (エディタの保管機能もあるし近年はディスプレイの画質も上がってきてるし) 伸ばせば良い。スコープの大きな変数であれば有るほど長い名前をつけると良い。

名前のフォーマットを決めると良い

class 名は CamelCase, 変数名は lower_separated, メンバ変数は後に _ をつける (ex. member_) 等。プロジェクトでこういう規約を作っておくと良さそう。

３章 誤解されない名前

動作が誤解される / 複数思いつく命名は避ける

  • filter → select or exclude
    • some_vec.filter("year <= 2021") だと 2021 以下が残るのか除外されるのかが分かり辛い
    • select (=残る) か exclude (=除外する) が良い
  • clip → remove or truncate
    • clip(text, length) だと後ろ length 文字を削除するのか length 文字になるように削除するのか分かり辛い
    • remove (=最後から length 文字削除) か truncate (=length 文字になるように切り詰める) が良い
    • length も max_length という書き方ができたり、単位が曖昧なのでこれに関する工夫が可能 (ex. max_chars, max_bytes 等)
  • bool 型 → is/has/can/should 等を付与
    • 否定形 (ex. disable_ssl = false) でなく肯定形 (ex. use_ssl = true) を使う (これ何度か問題になってるの見たことあるな...)
  • get*
    • get は常識的にはメンバ変数を返すだけの軽量な処理とみなされるらしい。なので、get 関数で重い処理をするのは NG らしい (本当か？)
    • 重い処理を書くなら、get → compute 等の方が良い。
    • 普段 get* で重い処理書いちゃってるので気をつけないと...。

６章 コメントは正確で完結に

入出力のコーナーケースに実例を使う

単にコメントに実例を書くとわかりやすいということ。sklearn の docstring とか見てても書いてあってわかりやすいよね。↓ みたいな感じ。

# 入力をソートする ex. [2, 1, 10, 9, 3] → [1, 2, 3, 9, 10]
def sort_values(inputs):
    ....
    return sorted_values

７章 制御フローを読みやすくする

条件式の引数の並び順

より『変化する』値を左に、より『安定的』な値を右に書く。例えば「もし君が 18 歳以上ならば」の方が「もし 18 年が君の年齢以下ならば」より理解しやすい。

１３章 短いコードを書く

コードを小さく保つ

プロジェクトの巨大化に際し、コードを小さく・軽量に維持する保つコツ

  • util 系のコードを積極的に書く・利用する
  • 不要なコード・機能は積極的に削除する (そこに費やした時間が無に帰するように見えて心苦しいかもしれないが)
  • プロジェクトをサブプロジェクトに分割する
  • コードの『重量』を意識する。軽量で機敏にしておく。

１４章 テストと読みやすさ

テストを読みやすくする

  • テスト関数の中の処理についても、できるだけ重複処理や冗長な処理をを関数化してより人間の思考でたどりやすくする。
    • 普段自分が書くテストでは結構テストデータとその加工を直書きしちゃったりしてるので気をつけよう...。
  • 関数が行っていることを極力分割して解釈し、２つ以上ある場合はそれぞれ個別にテスト (+できればどちらもをカバーしたものも) する。
  • テストしやすいように開発すると、より良いコードがかけるようになる。
    • ただし、テストのためにテスト対象のコードの可読性や性能を犠牲にするのはやりすぎ。

以上！