リーダブルコードに共感出来ない人とは一緒にコーディングしたくない

煽り気味のタイトルだけど、実際に感じたことなのでそのままタイトルにしてみた。

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

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

ソースコードは読み物です。読者は2種類います。コンピューターと人間です。
コンピューターが読みやすいようにという点ではアルゴリズムやデータ構造が該当するのだと思います。
では人間が読みやすいコードとは?
この本では色々な観点からその答えを提案してくれます。

サンプルコードはC++JavaScriptが多かったかな。
PythonJavaもたまに出てきますが、全体通して別に気にならない。
疑似コード読む感覚で読んでた。

読書記録として、特に心に響いたところをいくつか抜粋します。
実際にはここに挙げた他にもまだあって、すごい勉強になった。

はじめに

  • 挿絵

この挿絵に共感出来る人は買って損しないと思います。

1章 理解しやすいコード

コードは他の人が最短時間で理解出来るように書かなければいけない
(P.3)

この本ではこれを「読みやすさの基本定理」としていて、
各章いろいろな観点から説明が入るが「読み手が理解しやすいように」という姿勢は一貫して変わらない

コードは短くしたほうがいい。だけど、「理解するまでにかかる時間」を短くするほうが大切だ。
(P.4)

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

BinaryTreeというクラスのSizeメソッドに対して

このSize()メソッドは何を返すのだろうか? ツリーの高さ? ノードの数?
ツリーのメモリ消費量? Size()では何も情報が伝わらない。目的に適した明確な名前をつけるなら、
それぞれHeight()・NumNodes()・MemoryBytes()になるだろう。
(P.11)

そこまで考えずに安直に汎用的な名前を付けちゃう時があるなと反省しました。

tmpやretvalなどの汎用的な名前を避ける
(P.12)

変数名「ret」とか結構やっちゃう。手抜きなんだよなきっと。
ちなみに「汎用的な名前を使うときは、それ相応の理由を用意しよう」とも言っています。
ダメ絶対、ってわけではない。

名前は短いコメントのようなものだ。
(P.19)

3章 誤解されない名前

データベースの問い合わせ結果を処理するコードを書いているとしよう。
(中略)
どちらかよくわからないのは、filterがあいまいな言葉だからだ。
これでは「選択する」のか「除外する」のかわからない。filterという名前は避けるべきだ。簡単に誤解を招いてしまう。
「選択する」のであればselect()にしたほうがいい。「除外する」のであればexlude()にしたほうがいい。
(P.30)

filterとかたぶん書いていた。

読み手に疑問を抱かせるよりも、関数名をTruncate(text, length)に変えるほうがいい。
(P.31)

読み手に疑問を抱かせるような名前はアウト。

多くのプログラマは、getで始まるメソッドはメンバの値を返すだけの「軽量アクセサ」であるという規約に慣れ親しんでいる。
この規約を守らなければ、誤解を招く可能性がある。
(P.34)

「普通はこうでしょ?」っていう動きから逸脱するとよくない。

4章 美しさ

美しさと優れた設計は独立した考えだと思っている。
(P.42)

見た目が美しいコードのほうが使いやすいのは明らかだ。
(P.43)

一貫性のあるスタイルは「正しい」スタイルよりも大切だ。
(P.53)

この章はコメントの書き方とか実際に読みながらが楽しいところなので、文章としてはあまり線引いていない。

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

この章と次の6章は特に良かった。今までコメントを馬鹿にしてたのを反省した。
プログラミング覚えたてのころは無意味なコメントをたくさん書いていました。
コンストラクタに「コンストラクタ」なんてコメント書いたりしていました。
ある程度経験を積んで「コード読めば分かることをコメントに書くな」ということを覚え、
次第に「コメントが必要ないような明快なコードを書け」と思うようになりました。
コメントには「Why」(なぜそうしているのか)だけ書けばいいと信じていました。

だんだんと「コメントが本当に必要なのは稀で、普通は必要ないでしょ」と考えるようになりました。
ところがこの5、6章を読んで、再度考えが改まりました。

コメントを読むとその分だけコードを読む時間がなくなる。コメントは画面を占領してしまう。
言い換えれば、コメントはそれだけの価値を持たせるべきなんだ。
(P.57)

コードからすぐに分かることをコメントに書かない。
(P.58)

ここまでは前述の自分の考えと同じなので、だよねだよねと頷きながら読んでいました。
ところが次の一文でハッとさせられました。

この「すぐに」が大切だ。
(中略:ここでたった一行のコードと一行のコメントが例示される)
厳密に言えばこのコメントも「新しい情報」を提供していない。コードを見ればどのように動くかはわかる。
でも、コードを理解するよりも、コメントを読んだほうが早く理解出来る。
(P.58)

「コードを理解するよりも、コメントを読んだほうが早く理解出来る」
その方が、読み手に優しいでしょうというわけだ。なるほどーと思いました。
ちなみに本書を読んでもらえれば分かるけど、何でもかんでもコメント付けろという話ではありません。
あくまでもテーマは「他の人が最短時間で理解出来るように」。
そのためにはコメントが役に立つこともあるんだよ、というわけです。

一方で、処理に変更が入ったときにコメントの変更がされず、
整合性が取れなくなって逆に読みにくくなる、などの話もありますけどね。

優れたコメントというのは「考えを記録する」ためのものである。
(P.60)

関数やクラスを文書化するときには、「このコードを見てビックリすることは何だろう? 
どんなふうに間違えて使う可能性があるだろう?」と自分に問いかけるといい。
(P.65)

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

あいまいな代名詞を避ける
(P.72)

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

行数を短くするよりも、他の人が理解するのにかかる時間を短くする。
(P.89)

8章 巨大な式を分割する

短く書こうとして逆に分かりにくくなっていたことについての1文。

どうして1行で書こうとしたのだろう? そのときは「オレは頭がいい」と思っていたのだ。
ロジックを簡潔なコードに落とし込むことに一種の喜びを感じていた。
この気持ちはみんなにも理解してもらえると思う。まるでパズルを解いているような感じだ。
仕事は楽しくやりたいからね。問題は、これがコードのスピードバンプになっていたことだ。
(P.102)
※スピードバンプ:ここではコードを読む速度を遅くさせるものという意味

わかるわかるぞー。

9章 変数と読みやすさ

変数を適当に使うとプログラムが理解しにくくなる。
(P.112)

この後で挙げられている3つの理由と、そのあとに説明されている一時変数のレビュー基準がとても良い。

もっと理解しにくいのは、変数が絶えず変更され続けることだ。
(P.123)

そしてイミュータブルへ。

10章 無関係の下位問題を抽出する

小さな関数を作りすぎると、逆に読みにくくなってしまう。あちこちに飛び回る実行パスを追いかけることになるからだ。
新しい関数をコードに追加すると、ごくわずかに(でも確実に)読みにくさのコストが発生する。
(P.140)

そのコストを払ってまで関数化する必要があるか考えようという話。
このあたりはよく悩む。

11章 一度に1つのことを

タイトルで言い切っている感じ。
実例を読みながらって感じなので文章は特にピックアップなし。

12章 コードに思いを込める

「コードの動作を簡単な言葉で説明する」「説明中のキーワードに着目する」「それに合わせてコードを書く」
ということを実例を読みながらって感じなので文章は特にピックアップなし。

13章 短いコードを書く

プログラマが学ぶべき最も大切な技能というのは、コードを書かないときを知ることなのかもしれない。
(P.168)

YAGNI、車輪の再発明などに繋がることかなと。

14章 テストと読みやすさ

テスト関数の名前はコメントだと思えばいい
(P.191)

同意。だからこそ、日本語のテストメソッド名とか好き。
下手に英単語並べられるよりも分かりやすいから。

感想

普段から心がけていることが書かれていると後押しされたような心強さを覚え、
普段は意識していなかった観点で説明されるとなるほど今後は気をつけようと反省する。
とても良い本でした。