Book Review: The Missing Readme
I just started reading The Missing Readme after an interesting interview on Software Engineer Daily.
Some quick notes: It's written by real Software Engineers: Chris Riccomini and Dmitriy Ryaboy.
It deals with the practical aspect of being a Software Engineer and comprehensively covers how to create professional code, testing effectively, code reviews, continuous integration and deployment, design documents, and architectural best practices. It's targeted at new engineers but is equally relevant for senior software engineers.
A small criticism: I found the metaphors for various stages of the journey a bit confusing and a tad cutesy.
Ramp-Up Review (Team Newbie or Intern)
Cape Contributor (A First Real Project)
Operations Ocean (DevOps)
Competence Cove (Project Lead)
The section "Experiment with Code" could have been more balanced and clear on ways to experiment. The authors are fans of debuggers, but some developers (ME!!!) find test-first experiments, throw-away code in the Python console, and assertions more effective.
The "Read" section had great advice, but it was not particularly focused. It could have split into multiple sections. I loved the Ron Jeffries comments, "Code never lies. Comments sometimes do." and the call-out bubble on "Learning to Read Code" was helpful and that is such an important type of reading that it could have merited more detail. An entire section could have been dedicated to reading code.
The behavioral advice on how to interact is excellent. For any engineer, approaching interactions with colleagues problem-solving is important and the book has some excellent guideposts.
The book has excellent practical advice on approaching the codebase, refactoring, using boring technology, avoiding rewrites, and good references to classics such as Martin Fowler's Refactoring: Improving the Design of Existing Code.
The Specific Coding guidelines are equally relevant to the Senior Engineers' journey as the Newbie's journey. Beginner mind, after all, right? Again, I didn't see the attention to assertions that should be in a newbie developers' guide. Otherwise, the advice is excellent: I loved the attention to writing Idempotent systems.
The advice on logging was sound. The advice on metrics was very source-oriented when modern tooling like X-ray can provide many of the important metrics without the need for instrumenting in code.
I have to agree on "Treat Configuration as Code." A clear and flexible configuration pattern is a sign of a well-architected system.
The chapter on tests was comprehensive and sound. It's targeted to the developer and the types of tests a developer writes. I especially liked this statement: "Don't depend on others to write tests for you." Be a grown-up, write tests. I also liked the appropriate respect given to Kent Beck's Test-Driven Development.
Moving to the Code Reviews, the book is exceptionally strong. I wish more developers followed the code review request highlighted in the book. Also, I came on some surprising wisdom which I will incorporate into my own plans for CI by not submitting reviews to trigger tests. Great advice on how to write code reviews and how to deal with conflict in code reviews.
The section on Delivering Software is solid and reflects standard DevOps practices. Again and again, the "Do's and Don'ts" section at the end of each chapter is a valuable summary reference that can guide any team looking to mature their release cycle.
The "On-Call" Section starts to proscribe a better way of working and does so in a way that conforms to my experience with on-call. An SRE escalation team could be built around the On-Call ideas outlined in this book.
The section working with your Manager is great advice and insightful, as is the final section on navigating your career.
The book itself is well-written, based on sound development principles, and applicable to Software Engineers at any level - not just New Software Engineers.