「分かりやすいコード」や「読みやすいコード」を書くための方法が書かれた『リーダブルコード』を実際に読んでみて、オススメする人や内容の要約を行いました。また、英語の無料PDF版の入手方法についても調べました。
『リーダブルコード』の要約と入手方法
超名著なので説明不要かもしれませんが、「分かりやすいコード」「読みやすいコード」を書くための方法が簡潔にまとめられている本です。
転職DRAFTの「エンジニアとして影響を受けた技術書ランキング2020年版」でも2位以下に5倍近くの差をつけてぶっちぎりの1位です(1位のリーダブルコードが131票、2位が28票)。
私は入社した頃に読みました。ポイントが簡潔に書かれていてすぐに実践できる内容が多く、本当に読んで良かったと思う技術書の1つです。
上司にコードレビューをお願いするときに自分以外に分かりづらい汚いコードを見せるのは嫌ですし、リファクタリングすることもあるのでその時の大きな指針になっています。
『リーダブルコード』をオススメする人
結論を言うのであれば、エンジニア全員。
ただし、プログラミング初学者が読む本ではないと思います。
Progateが終わったくらいのレベルで一回読むのは良いと思うのですが、プログラミングが分からない人が1冊目で読む本ではないです。
より具体的に、特におすすめする人は以下でしょうか。
- プログラミングの基本的な構文etc.を学び終わって(Progate卒業くらい)これから色々作ってみたいと思う人
→難しいところも多いと思うけど、とりあえず読んでみて1回読んでコードは分かりやすく書く必要があることを学ぶ。機を見てまた読み返すことをお勧めします。 - エンジニアとして仕事を始めた人
→チームで開発をするのにコードが読みにくいと困るため。
注意点
コードの書き方の良い例・悪い例として多くのサンプルコードが挙げられていますが、C++、Python、JavaScript、Javaで書かれています。これらのコードが読めないと具体例が分かりづらいかもしれません。
ただし、内容は書く言語に関係なく共通して使えます。
『リーダブルコード』の内容
目次
- 1章 理解しやすいコード
第I部 表面上の改善
- 2章 名前に情報を詰め込む
- 3章 誤解されない名前
- 4章 美しさ
- 5章 コメントすべきことを知る
- 6章 コメントは正確で簡潔に
第II部 ループとロジックの単純化
- 7章 制御フローを読みやすくする
- 8章 巨大な式を分割する
- 9章 変数と読みやすさ
第III部 コードの再構成
- 10章 無関係の下位問題を抽出する
- 11章 一度に1つのことを
- 12章 コードに思いを込める
- 13章 短いコードを書く
第IV部 選抜テーマ
- 14章 テストと読みやすさ
- 15章 「分／時間カウンタ」を設計・実装する
1章 理解しやすいコード
コードを改善するたった1つの鍵は、コードは理解しやすくなければならないというもの。
あとから自分や他人が見ても分かるように、コードは他人が最短時間で理解できるように書く。
2章 名前に情報を詰め込む
- 明確な単語を選ぶ。例えばgetやstopはあまり明確な単語ではないので、それぞれfetchやdownload、killやpauseを用いた方が良い。
- tmpなどの汎用的な名前やi,j,kなどのループイテレータを意味のある名前にすることで、バグを見つけやすくなる。(処理を忘れたり、イテレータを逆にしていることを見つけやすくなる)
- 間違えたらバグになりそうなとき、変数名にフォーマットセキュリティ上の属性、単位を入れるのは有効。plaintext_や_mbなど。
- 不要な単語を捨てる。例えばDoLoop()の最初のDoはいらない。
3章 誤解されない名前
- 名前が他の意味と間違えられることはないだろうか？と何度も自問自答する 。
- 限界値を含めるときはminとmaxを使う。(変数名にmaxやminをつけることによって、条件文を書くときにその値を含めるべきか否かが分かりやすい。)
- 範囲を指定するときはfirstとlastを使う。これらを使うことで包含していることが明確になる。
- 排他的範囲にはbeginとendを使う。
- bool値の変数はisやhasなどの単語を使うことで、Trueとなる状態とFalseとなる状態が分かりやすくなる。(例:read_passwordよりもuser_is_authenticatedの方が状態が分かりやすい)
- getX()やsizeX()は軽量なメソッドが期待されているので、重い処理を書かないようにする。
4章 美しさ
- 適切な改行を入れるようにし、コメントも整列させる。
- 重複がある場合は、メソッドを使ってコードを簡潔にすると良い
- 縦の線をまっすぐにする。
- 宣言は空行を用いて適切なブロックにまとめる。
- 順番を守る。ある場所で並べた順番を他の場所で変えないようにする。
- プロジェクトでスタイルを統一する。正しいことよりも一貫性が大切。
5章 コメントすべきことを知る
- コメントの目的は、書き手の意図を読み手に知らせること
- コードからすぐ分かることは書く必要がない。
- ひどい名前の説明をするためにコメントを書いてはいけない。名前を変えよう。
- 作った意図や経緯を書く(〇〇ができなかったのでこのようになった、××のように改善したほうが良いかもしれないなど)。あとからできなかった最適化しようとして失敗したり、バグだと思って修正しようとすることを防ぐ。
- コードの欠陥にコメントをつける。(例えばTODO: FIXME: HACK: XXX:などを用いる)
- 定数にコメントをつける。なぜその値になっているのか分からないため。
- 読み手の立場になり、質問されそうなところやハマりそうな罠、全体像にコメントを残す。
6章 コメントは正確で簡潔に
- コメントは領域に関する情報の比率が高くなければいけない。
- ダラダラとした文章や代名詞を避け、正確かつ簡潔に書く。
- 慎重に選んだ(コーナーケースの)入出力の実例を使ってコメントを書く。
- 分かりにくい引数にはインラインコメントを使う。
- 専門用語などの情報密度の高い言葉を使う。
第7章 制御フローを読みやすくする
- 条件やループなどの制御フローはできるだけ「自然」に書く
- if文は左側を「調査対象」、右側を「比較対象」にする(例：if(a<3)はif(3>a)より読みやすい)
- if/else文は条件は否定形より肯定形を使う、単純な条件を先に書く、関心を引く条件や目立つ条件を先に書く
- 三項演算子は読みにくいので、それによって簡潔になるときだけ使う。
- do whileループはwhileループで書き直せることが多いので避ける。
- 関数を使う時はreturnを早く返すことで読みやすくなる
- gotoは使わない
- ネストを浅くする。深いと読みにくい。修正するときにコードを新鮮な目で一歩下がって全体を見ることで、ネストが深くなることを防ぐことができる。
- 「失敗ケース」をできるだけはやく返すことで、ネストを削除できる。
第8章 巨大な式を分割する
- コードの式が大きくなるほど理解が難しくなるため、巨大な式は飲み込みやすい大きさに分割する。
- 式の値を保持する「説明変数」を使う。
- 式を説明する必要がない場合でも、管理や把握を簡単にするために式を変数に代入する「要約変数」を使う。
- bool演算子は短絡評価を行うものが多いので注意(a||bでaがtrueであった場合にbが評価されない)。1行で書く必要はないので論理式が複雑になりすぎないように注意。
9章 変数と読みやすさ
- 役に立たない一時的な変数や中間結果を格納する変数は削除してよい。
- 制御フロー変数はうまくプログラミングすれば削除できる(例:while(!done){}文中のdone)
- グローバル変数だけではなく、すべての変数のスコープを縮める。理由は一度に考えなければいけない変数を減らせるから。メソッドをできるだけstaticメソッドにする、大きなクラスをできるだけ小さなクラスに分割するという方法がある。
- 変数は一度だけ書き込む。変数を操作する場所が増えると、現在地の判断が難しくなるため。
第10章 無関係の下位問題を抽出する。
- 無関係の下位問題を抽出することで、コードは大幅に改善する。方法は以下。
- 関数やコードブロックを見て「このコードの高レベルの目標は何か？」と自問する。
- コードの各行に対して「高レベルの目標に直接的に効果はあるのか？無関係の下位問題を解決しているのか？を自問する」
- 無関係の下位問題を解決しているコードが相当量あれば、抽出して別関数にする。
- プロジェクトとは無関係の汎用コードを作る。
- インターフェースが理想とはかけ離れていたら、自分でラッパー関数を作ればよい。
第11章 一度に1つのことを
- コードは1つずつタスクを行うようにしなければならない。方法は、コードが行っているタスクを列挙し、それをできるだけ異なる関数に分割する。
- どのように分割するのかよりも分割することが大事。
第12章 コードに思いを込める
- 誰かに複雑な考えを伝える時は、自分よりも知識が少ない人が理解できるような「簡単な言葉」で説明する能力が大切であり、コードを読み手に伝える時も同じ。
- 以下のステップでコードをより明確にできる。
- コードの動作や簡単な言葉で同僚にも分かるように説明する
- その説明の中で使っているキーワードやフレーズに注目する
- その説明に合わせてコードを書く
第13章 短いコードを書く
- 最も読みやすいコードは何も書かれていないコード。
- プロジェクトが成長しても、コードをできるだけ軽量に維持しなければならない。以下のことをしなければならない。
- 汎用的な「ユーティリティ」コードを作って、重複コードを削除する。
- 未使用のコードや無用の機能を削除する。
- プロジェクトをサブプロジェクトに分割する。
- コードの「重量」を意識する。軽量で機敏にしておく。
- 最も簡単に問題を解決できるような要求を考える。
- ライブラリの機能を熟知して活用することが大切なので、たまには標準ライブラリのすべての機能・モジュール・型の名前を15分かけて読んでみよう。
第14章 テストと読みやすさ
※ここでの「テスト」は他のコードの振る舞いを確認するためのすべてのコード
- 他のプログラマがテストの追加や変更ができるように、テストコードを読みやすくする。
- 大切でない詳細はユーザから隠し、大切な詳細は目立つようにする。ヘルパー関数を用いるとよい。
- テストの本質というのは、「こういう状況と入力から、こういう振る舞いと出力を期待する」ということであり、1行でまとめられることが多い。
- エラーメッセージを読みやすくする。便利なアサーションメッセージを使ったり、手作りのエラーメッセージを使う。
- テストの入力値は、コードを完全にテストする最も単純な入力値の組み合わせを選択しなければならない。
- コードを検証する「完璧」な入力値を1つ作るのではなく、小さなテストを複数作る方が、簡単で効果的で読みやすい。
- テストの機能に適切な名前を付ける。
『リーダブルコード』の購入方法・英語の無料PDF版の入手方法
購入方法
インターネットだとAmazonやO'Reilly Booksから購入できます。
Kindleに対応していないため、Amazonで購入できるのは単行本のみです。
O'Reillyのサイトでは電子書籍版も買うことができます。
私はここからPDF版で購入し、Kindleに入れて読みました。
定価は単行本が\2,640、電子書籍版が\2,112です。
英語版の無料PDFがある？
Google先生がサジェストしてみたので調べてみたところ、英語版の無料PDFが転がっているようです。
英語の題名+freeでググったら上の方に普通にPDFで全文出てきました。
「The Art of Readable Code: Simple and Practical Techniques for Writing Better Code (English Edition) free」ですね。
(上記で検索すれば出てきますがリンクはこちらです。)
何度も読み返せますし本当に役立つ1冊なので、よほどの英語強者でない限りケチらないで日本語版を買って読むことを個人的にはお勧めします。
ただ、書かれていることは概念的なことではなく実践方法みたいな感じですし、英語でもある程度は意味を理解できそうです。
コメント