リーダブルコード読書エントリ[Part1]

リーダブルコードを読んでみたので、定着させるためにもこの記事を書いてみることにしました！
今回はPart1ということで、全4部のうちの1部を紹介します。

そもそもリーダブルコードってどんな本？

簡潔に言うならば「コードの可読性」に焦点を当てた本です。「具体的な～について紹介する」という技術書は多いですが、この本はどの言語にでも汎用的に適応できるノウハウが書かれています。例えば、命名規則についてだったり、コメントについてだったり、「素通りしがちだけど本当は大事だよね！」ということを全231ページにわたって解説しています。

本の内容

この記事では、本の内容をすべて書こうとは思っていません。重要そうだと思ったり、参考になった部分だけ、かいつまんで書いていきます。

名前に情報を詰め込む

変数や関数の名前についてです。命名について注意すべき主な二点について書いていきます。

明確で具体的な変数名にすること

意味が絞り切れない変数名や、処理内容を表現しきれていない変数名にすべきではありません。
例として、円周率を計算して返すgetPi()という関数を考えてみます。関数名だけを見ると円周率を返すのだろうとはわかりますが、計算しているという情報は読み取れません。

    const pi = getPi();// 計算してるの？ただとってきてるだけ？

つまり、明確ではありません。
「円周率を返す」と「円周率を計算する」では、計算するのほうが大切な情報（計算してその結果を「返す」のは示さずとも予想できるため）なので、この場合はcalculatePi()とすべきです。

    const pi = calculatePi();// 計算してるんだね！代入してるってことは戻り値は円周率かな？

スコープの長さに応じて変数の長さを決めること

スクロールが必要なくらいスコープの長い変数は、変数を見ただけでも何が入っているかわかる名前にすべきです。逆に、数行のスコープで済む場合は、冗長になるので変数名を長くするべきではありません。
例えば、APIレスポンスとして、ゲーム大会の優勝者名を返す場合を考えます。このとき、返す値の変数名は優勝者の名前なので、winnerNameと表現できます。しかし、これだと、“何に”勝った人の名前なのかわかりません。したがって、変数名はvideoGameCompetionWinnerNameとすべきです。

コメントについて

ひどい名前にはコメントをつけるのではなく名前を変える

先ほどの例で出した円周率を計算して返すgetPi()を考えてみましょう。この関数名では「計算している」という情報が抜けています。「関数を説明するコメントをつければよいのでは？」と思った方もいるかと思います。しかし、先の例で説明したように、関数名をcalculatePi()とすれば、コメントは必要なくなります。

//  円周率を計算して返す
    const pi = getPi();

より

    const pi = calculatePi();

のほうが簡潔で分かりやすい。

自分の考えをコメントする

「どうしてこの処理を書いたのか」、「別の処理ではいけなかったのか」をコメントで残しておくとプログラム修正時に役立つことがあります。
例えば、

//  精度より速度が必要なので、計算量の小さい方法で許容できる精度の答えを求めている

と書いておけば、後に自分以外の人が「遅いが最適な答えが求まるコード」に置き換えてしまうことがなくなります。

また、定数にコメントをつけておくのも良いです。例えば、

//  一秒間のリクエスト数は100で見積もっておけば十分
    MAX_RWQUESTS_PER_SEC = 100

と書いておけば、勝手な書き換えを防ぐだけでなく、リクエスト数が上限を超えそうになったときに書き換えることも可能です。

要約コメント

一行のコードにだけではなく、複数行にわたるコードに対してコメントをするのも良いです。

//  バリデーション
    （処理）
//  DBからデータを取得
    （処理）
//  レスポンスを整形
    （処理）

細かい処理を読まずに処理の概要を把握できるため、プログラム全体の見通しが良くなります。

Part1　まとめと感想

以上でPart1は終了です！
振り返ってみると、当たり前なことばかりですが、意識していないと実践するのは難しいと思います。特に、コメントについては自分の視点だけでは書けないので、いったん自分で書いたプログラムを客観視することが必要そうです。

次回のPart2は、今回のような表面的な改善だけではなく、ループなどの処理の内容に突っ込んだ改善を紹介することになりそうです。