The Missing READMEという新人ソフトウェアのためのエンジニアガイドの書籍を読んだ感想です。

The Missing READMEはコード、設計、テスト、リファクタリング、例外処理やログ、依存管理、コードレビュー、CI/CD、インシデント対応、コミュニケーションやプロジェクト管理など幅広いことがすっきりとまとまってる感じの書籍です。

全体的に説明に出てくるコードは少なめです。逆を言えば特定のプログラミング言語に依存していないので読み物として読みやすかったです。 （類似することを体験した）後で書籍を見直すとこれのことだったのかーと思うような話が多い感じでした。（自分は今日からはじめる情報設計という書籍でこれをよく経験した）

全部で300ページもない書籍なのですが、ここまでいろいろなカテゴリの話をしていて、それでいて読みやすくまとまっているのは結構すごいなと思いました。 こういう書籍は、辞書的な見出し(~~の法則)みたいな感じになりやすい気はしますが、そういう感じでもなくちゃんと意味あるまとまりになっていたのが読みやすい理由なのかなと思いました。

日本語だと次の書籍が近いジャンルだと思います。

ただそこまでコードという印象はなくて、エンジニアリングという印象の書籍だったかなと思います。

全体的な雰囲気のメモとして、気になった章ごとの軽い感想をメモっておきます。

The Missing READMEの主な章ごとの感想

4章: Writing Operable Code

Chapter 4: Writing Operable Codeは結構良かったです。 特に”Throw Exceptions Early, Catch Exceptions Late”というセクションが良かったです。

Throw Exceptions Earlyは、例外は早い段階投げることで問題を特定しやする話です。例外を投げる場所を遅らせると別の例外が発生して問題がわかりにくくなる場合があります。 Catch Exceptions Lateは、例外は正しくハンドリングできる処理までそのエラーを伝搬する話です。途中で例外を握りつぶしてしまうのは問題をわかりにくくしてしまう問題があります。

コードを書いていると自然とそのような形になると思いますが、これを”Throw Exceptions Early, Catch Exceptions Late”という言葉でまとめているのが良かったです。

📝 JavaScriptにもようやくError Causeというエラーの情報を連鎖的させられるようになりました。これでエラーを上流に持っていくのが素直に書きやすくなります。

4章は他にもログの出し方の話でログレベル、機密情報をログしない、設定ファイルを賢くしすぎない、設定ファイルの完全な状態をログとして残す、設定ファイルはロードしたタイミングで検証するといった話が書かれています。それぞれはどこかで見たことがあるけど、こういう感じでまとまってると読みやすくていいなーと思いました。

あと、The Missing READMEは章ごとのまとめにDo and Do notの形でまとめがあるので、これもわかりやすかったと思います。 次の図はChapter 3: Working with Code | The Missing READMEのまとめです。

5章: Managing Dependencies

Chapter 5: Managing Dependenciesでは、パッケージマネージャの話ですが、特定の言語に依存はしてないのが面白い切り口でした。 セマンティック バージョニングやバージョン番号としてGitハッシュ値は適していない話、依存関係地獄の話、依存関係のレポーティングの話など。

7章: Code Reviews

Chapter 7: Code Reviewsのコードレビューの話も結構良かったです。 いわゆるコードレビューのする側、される側の作法的な話ですが、Google Engineering Practices Documentation | eng-practicesも例にだして、どこまでレビューするべきか(どこでApproveするべきか)話が書かれています。

これ自体は、Google Engineering Practices Documentationの話ですが、そのPull Requestがシステム全体の健全度を向上させる状態に一度でも達したらならば、そのコード/PRが完全ではなくても、レビューアは承認(Approve)するべきという基準の話は良かったです。

In general, reviewers should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn’t perfect. https://google.github.io/eng-practices/review/reviewer/standard.html

The Missing READMEは章末の”Level Up”というセクションで参考書籍や次に読むべきリソースへの誘導も入ってるのも結構いいところです。

8章と9章: デプロイとオンコール

Chapter 8: Delivering Softwareは”Delivery consists of steps such as release, deployment, and rollout.“という話で、それぞれのステップを一個ずつ見ています。 Chapter 9: Going On-Callは、オンコールの仕組み、サポートチケットの切り方(P1からP4)、インシデントマネージメントにかかれています。 この２つの章を”A Guide for the New Software Engineer”に入れてるのは結構すごいなーと思いつつ、一番混乱しそうなところでもあるのでガイドがあるのは良い気がしました。

10章と11章: 設計

Chapter 10: Technical Design Processは、仕様やデザインドキュメントの話(実験的なコードに執着しすぎない、それは変わる)、デザイン批評的なコミュニケーションの話。 Chapter 11: Creating Evolvable Architectures | The Missing READMEは、後方互換性と先方互換性の話です。

他にも、Agile、マネージメント、キャリア的な話もあったりします。

その他

扱ってる内容はかなり幅広いですが、章ごとの依存関係はほとんどないように書かれている気がするので、どこから読んでも大丈夫な気がしました。 300ページぐらいでこれまとめたのは素直にすごいと思ったので、どこからか翻訳が出版されるといいなーと思いました。（ちゃんと外部リソースにリンクにして説明しすぎないことに気を配ってる気がしました）

自分はACM会員のO’Reilly Learning Platformを利用できる仕組みを使って、オライリー上のThe Missing READMEを読みました(Thanks to 📖 Book Supporter)