リーダブルコード — 引き継ぐ側に回って分かったこと

自分で書いていないコードを直す仕事が続いた時期がありました。書いた人はもういません。仕様書もありません。あるのは動いているコードだけです。

読んでいて思ったのは、これを書いた人を責めても何も進まないということでした。同時に、自分が書いたものも、いずれ誰かにこう読まれるということでもあります。

読めないコードは、読みにくいコードとは限らない#

最初に困ったのは、きれいに整っているのに何をしたいのか分からないコードでした。

字下げは揃っています。短い関数に分かれています。それでも読めない。理由を探していくと、名前でした。

const data = getData();
const result = process(data);
if (flag) {
  doIt(result);
}

形としては悪くありません。ただ、この4行を読んでも、何の処理なのかが1つも分かりません。名前が全部「何かの入れ物」で止まっています。

この本が答えていること#

この本は、そういう「読む側の負担」を軸に書かれています。副題が「より良いコードを書くためのシンプルで実践的なテクニック」で、扱っているのは設計論ではなく、もっと手前の話です。

名前の付け方、コメントに何を書くか、条件分岐の並べ方、1つの関数にどこまで詰めるか。どれも今日書く1行に効く内容で、大きな作り替えを必要としません。

いちばん残ったのは、コメントには「何をしているか」ではなく「なぜそうしたか」を書くという指摘でした。

// ユーザーを取得する
const user = fetchUser(id);

これはコードを日本語に訳しただけで、読む側は何も得ていません。知りたいのは、なぜここで取りに行くのか、なぜこの方法なのかのほうです。

引き継ぐ側にとって、いちばん欲しかったもの#

実際に困った場面を思い返すと、欲しかったのは常に判断の理由でした。

右の列が分からないと、触っていいのかどうかが判断できません。一見無駄に見える処理が、実は過去の不具合への対処だった、ということは珍しくありません。理由が書いていないと、消して初めて分かります。

読んだあとに変えたこと#

このサイトのコードでは、コメントの書き方を変えました。処理の説明ではなく、なぜその選択をしたのかを残すようにしています。

たとえば「この値を1か所にまとめた理由」や「この設定を別のファイルに切り出した理由」を、選ばなかった案と一緒に書いています。半年後の自分は、今の自分が何に困っていたかを覚えていません。困りごとごと残しておかないと、また同じ場所で悩みます。

合わないかもしれない場合#

扱っているのは小さな単位の話なので、設計全体をどう組むかという話は出てきません。そこを求めて読むと物足りなく感じます。

あと、例に使われているコードはC++やJavaScriptなどが中心です。普段そのあたりを書いていなくても読めますが、言語固有の書き方を学ぶ本ではありません。考え方を持ち帰って、自分の言語に翻訳する読み方になります。

今回の学び#

まず、コードは書く時間より読まれる時間のほうが長いということ。引き継ぐ側に回って初めて実感しました。書いているときは自分しか読者がいませんが、動き続けるコードには読者が増えていきます。

次に、名前は飛ばし読みのための道具だということ。読む人は全部を読みません。名前で当たりを付けて、必要な場所だけ開きます。名前が中身を表していないと、この省略が使えなくなります。

そして、残すべきは処理ではなく判断だということ。何をしているかはコードを読めば分かります。分からないのは、なぜそうしたかのほうでした。そこが書いていないと、後から来た人は消すことも直すこともできません。