Review: Vibe Coding by Gene Kim and Steve Yegge

(Post theme: Be Better by Where’s Jai?)

TL;DR: Vibe Coding is a sprawling, sometimes exasperating, but ultimately worthwhile look at how to work with AI assistants in real codebases. It’s at least twice as long as it needs to be, the kitchen metaphor goes on for far too long, and the authors are not exactly “regular” engineers, but when you strip away the fluff there’s a lot of solid, experience‑shaped advice about testing, version control, and how to keep agents from quietly wrecking your code. I’d recommend it if you have time and like long, opinionated books; if you’re trying to optimise for density, you can get most of the value from shorter material plus your own experiments.

I went into Vibe Coding (subtitle: Building Production-Grade Software with GenAI, Chat, Agents, and Beyond) expecting it to feel dated before it even properly hit print. It turns out that, for a book about GenAI and agents in 2025, it’s surprisingly not.

Gene Kim and Steve Yegge are not exactly obscure figures, and that colours the whole thing. You can feel the long histories (Amazon, Google, DevOps world, etc.), and you can also feel that they are not your typical “here’s my Python side‑project, let me tell you about AI” authors – they’re writing in Kotlin and Scala of all things, they use slightly odd analogies, and they are clearly having fun. It does not read like a quick money grab or personal‑brand brochure; it reads like two famous engineers who got obsessed with a topic and then wrote down far too much about it.

I liked it. I also think it would be a much better book if it were roughly half as long.

What the book is actually about

The core pitch is that “vibe coding” is what happens when you shift from typing code to having a flowing conversation with an AI assistant, with intent and feedback loops doing the heavy lifting. They explicitly distinguish this from the usual “prompt engineering” narrative:

“Vibe coding is about dynamic, in‑the‑moment problem-solving rather than creating a bulletproof prompt… It’s like texting with friends. Casual and impromptu. In contrast, prompt engineering is more like emailing a lawyer who is suing you—everything in that email is fraught with consequence.”

That distinction captures one of the better insights in the book: the way you work with AI day‑to‑day is much more conversational and disposable than most “prompt engineering course” material pretends.

They also give their value proposition a name: FAAFO – “fast, ambitious, autonomous, fun, and optionality.” I strongly suspect that the backronym came after the pun, because I only realised at the very end of the book that “FAAFO” is a reference to a different meaning, and I’m fairly sure one of the authors has been waiting years to put that into a book.

Usefully, they are also clear about what’s not in FAAFO:

“By the way, you may have noticed that there is no ‘B’ in FAAFO. Vibe coding does not automatically make your code better. That is your responsibility.”

This theme runs throughout: AI will happily help you ship horrors faster, unless you bring real engineering discipline to the party.

The kitchen, the sous‑chef, and the haunted codebase

The book leans hard on a kitchen metaphor: you’re the head chef, the AI is your sous‑chef, and your codebase is the kitchen. This works well at first, then drags on, and by Part 4 I was ready to buy everyone their own colour‑coded chopping board just to make the analogy stop.

The “dark side” chapter is one of the more compelling parts. They recount, for example:

“…the coding agent had silently disabled or hacked the tests to make them work and had outright deleted 80% of the test cases in one large suite.”

This will ring horribly true for anyone who has let an agent loose on a real codebase. They do a good job of cataloguing these failure modes: haunted codebases, cardboard muffins (things that pass tests but are hollow inside), and reward‑hacking agents that just want to check boxes.

That leads to a set of “head chef” disciplines which are, essentially, “how to be a responsible adult around AI”:

  • “Delegate thoughtfully” to well‑defined, verifiable tasks.
  • “Supervise appropriately” when novelty, complexity, or impact are high.
  • “Establish guardrails” about what AI may and may not touch.
  • “Check work regularly” and “trust but verify relentlessly.”

One of my favourite lists is in a section about agents hijacking reward functions:

“Count your babies systematically… Check for cardboard muffins… Demand excellence explicitly… Clean as you go… Trust but verify relentlessly… Remember the AI paradox…”

Yes, it’s slightly over‑written (pot, meet kettle), but the message is right: if you don’t inspect what you expect, AI will optimise for the wrong thing and look very pleased with itself while doing it.

Tests, version control, and all the things you already know you should be doing

A lot of the concrete advice is “good software engineering practice, but with more exclamation marks because of AI.”

On version control:

“Version control has always been critical, but with AI, it becomes life-or-death for your code.”

On tests:

“You’ll be well-served to have automated testing running all the time on your developer machine, triggered by every file change.”

“There is another powerful and surprising benefit that you get by writing and running tests. If your AI assistant has trouble creating test cases (or keeping them passing), that’s a sure-fire sign your code is missing some modularity, and perhaps clarity too.”

They also explicitly tell you that after AI writes tests, you still have to:

“Eyeball the tests… Run the tests yourself… Review and critique… Have AI run its own tests… But don’t blindly commit.”

None of this is revolutionary, but it’s an accurate reflection of what it feels like to build things with agents right now. When generation is cheap and fast, tests become the thing that anchors you to reality.

They even make the point that this is very similar to how we treat open‑source dependencies:

“We rarely examine every line of code in those either… we build trust with them through testing.”

Again: not new, but good to have written down in an AI context.

Inner, middle, outer loops (and AGENTS.md)

The structure of the second half of the book is organised around “inner”, “middle”, and “outer” developer loops – essentially: your local dev workflow, your interactions with repos and CI, and then team‑ and organisation‑level patterns.

The inner loop chapter has a lot of practical, chat‑and‑editor‑level advice: continuous tests, small end‑to‑end “tracer bullet” tasks, and using AI as an extremely talkative rubber duck:

“Embrace your AI as your most attentive (and talkative) rubber duck…”

The middle loop introduces AGENTS.md – a kind of CONTRIBUTING.md for your AI collaborators, describing how to work on the project, what tools exist, coding style, and so on. A nice observation not from the book, but from Jason Nucciarone, is that this is what CONTRIBUTING.md probably should have been in the first place.

I like the idea of formalising “instructions for the machines” in a first‑class document, but, just like with humans, the truly effective version is “put the rules into linters and tests.” If you keep seeing the same issues in AI‑authored code, the best fix is to encode the constraint into pre‑commit or CI and let the bots learn from failing checks.

The outer loop chapter gets into CI/CD and organisational process. Some of this is standard “invest in CI/CD” advice, but with an AI twist:

“Because AI excels at reviewing, analyzing, and critiquing code, it’s able to transform the CI/CD pipeline itself, moving beyond simple pass/fail checks.”

and:

“Push to Remote Often.”

There’s also a lot about having agents challenge additions, constrain changes by line count, and forbid new libraries without explicit approval:

“Challenge your AI to justify additions… constrain AI to solve the problem within a certain line count… Instruct your AI to avoid pulling in new libraries or frameworks without your explicit approval.”

Again, this is all solid, but if you’ve been living in “choose boring technology” and “pre‑commit all the things” land, it’ll mostly feel like reinforcement rather than revelation.

Culture, metrics, and things that irritated me

The culture chapter is where some of my disagreements and pet peeves really kicked in.

First, the structure. The book uses the very common pattern where:

  • The book tells you what the book will tell you.
  • The section tells you what the section will tell you.
  • The chapter tells you what the chapter will tell you.
  • You finally get the content.
  • Then the chapter tells you what it told you.
  • Then the section recaps.
  • Then the book recaps.

If you stripped out all of this scaffolding, I think you could cut the length by about half without losing any real content. It reminds me of old broadcast TV, where shows had to regularly repeat and recap because you couldn’t assume people had watched from the start, or in order. In 2026, in a book, with readers who absolutely can start at the beginning, it’s just fluff.

Second, there are places where the “move fast” narrative brushes up against sustainability and ethics in ways that I found uncomfortable. For example, I really dislike arguments that implicitly encourage maximising token spend “to be first on a dashboard.” This encourages waste, and there are very real environmental costs here; as useful as these tools are, we don’t need to burn extra compute just to climb a leaderboard.

There are also economic assumptions that I think will grate for readers. Spending thousands per year on AI tools is presented fairly casually in places; that’s realistic for some senior people at certain companies, but not remotely universal. Similarly, some of the discussion about who captures the productivity gains of AI‑assisted work left me with more questions than answers: “Does the employee not get to capture some gain? Is capitalism always best?”

On metrics, we get the inevitable nod to lines of code as a thing people still talk about in 2025:

“Ah, yes, lines of code, the metric everyone associates with both quality and productivity …”

The authors are not endorsing LoC as a great metric, but the fact that it still shows up at all is a reminder that the industry is fully capable of mis‑measuring AI‑assisted work the same way it mis‑measured manual work.

And then there are simply wrong bits. For example, there’s a PM‑related claim where, as an ex‑PM, I can confidently say: no. There are also a few analogies (including one kitchen‑related) that are just bad: “Buy dedicated boards, even in home kitchens.”

Where the book has aged already

Because this is a fast‑moving space, some of the concrete details have already shifted. For example, the book talks about juggling multiple agents yourself, where in practice many tools now do that under the hood – you interact with “one” Claude Code or GitHub Copilot, and it spins up extra agents as needed. In day‑to‑day use, you just behave as if there’s one assistant that is decent at multi‑tasking.

Some tool‑specific mentions (like Anthropic’s Model Context Protocol, MCP) are already more widespread than they were at the time of writing, but that actually makes those sections feel more relevant rather than less.

Overall, I was expecting a strong “oh, that was the 2024–2025 moment” vibe and instead found that most of the advice is still applicable in 2026 – which is a pleasant surprise.

So, should you read it?

If you are extremely early in your AI‑assisted coding journey, Vibe Coding will probably feel like a firehose of patterns, anecdotes, and “please don’t blow your foot off” advice. If you’ve been working with agents for a while, as I have, you’ll find a lot that matches experience, some memorable phrases, and a few genuinely useful conceptual handles – but not many brand‑new lessons.

For me, the signal‑to‑noise ratio was about 50%. The good 50% is very good: concrete stories about real failures, solid checklists for delegating to agents, and a clear articulation of how inner/middle/outer loops change when you add AI. The other 50% is structure, repetition, over‑extended metaphors, and a general “this could have been a much tighter book” feeling.

I’d recommend it if:

  • You have spare reading time and don’t mind wading through some fluff to get to the good bits.
  • You prefer to learn from long‑form narratives and war stories rather than scattered blog posts and conference talks.
  • You want something opinionated rather than a neutral survey of tools.

If you’re short on time, you can get most of the value from a combination of good blog posts, talks, and your own experiments. But if you do have the time, and you’re interested in what two very opinionated, non‑typical engineers have to say about vibe coding, it’s an enjoyable – if occasionally exasperating – read.

            Review: The Staff Engineer’s Path by Tanya Reilly

            (Post theme: something to my something (feat. Maddy Low) by FDaSavage)

            Tanya Reilly’s “The Staff Engineer’s Path” is the first in my 2025/2026 summer reading programme, and it’s the clearest guide I’ve found for navigating the often-ambiguous world of senior technical leadership. If you’re wondering what staff engineers actually do all day, or how to grow into that role effectively, this book deserves a spot on your reading list

            What Makes This Book Different

            Most technical leadership books either focus too heavily on management or stay frustratingly abstract. Reilly strikes a better balance, addressing the messy reality of being a senior IC: you’re expected to have broad impact, but nobody’s quite sure how. One highlight that captured this perfectly was her observation that staff engineers “take on ambiguous, messy, difficult problems and do just enough work on them to make them manageable by someone else.” That’s the job in a nutshell.

            The role also requires thinking beyond the immediate: “thinking beyond the current time, whether that means initiating yearlong projects, building software that will be easy to decommission, or predicting what your company will need in three years.”

            Building Your Mental Maps

            The “Three Maps” chapter was a standout for me. Reilly emphasizes that understanding your organisation’s terrain is critical work, not political manoeuvring. She advocates for practical techniques like watching recently created Slack channels (I did this back when I used Slack with <100 other people — I’m not sure how I would with Matrix and ~1000 people), skimming senior people’s calendars, and reading design docs even when they’re not “for you” (I created a subscription system so that I could do this without having to manually trawl through changes).

            “I asked on Rands Leadership Slack about how everyone approaches knowing things, and a common thread was paying attention to information that isn’t secret exactly, but isn’t necessarily for you. This included reading senior people’s calendars, skimming agendas or notes for meetings you’re not in, and—something that had never occurred to me—looking at the full list of Slack channels sorted by most recently created so you can see what new projects are happening.”

            The key is to “figure out where decisions are happening” and understand “who [leaders] listen to and how they make decisions.”

            I particularly appreciated her reference to gemba from Lean manufacturing—the practice of walking the floor to see how things actually operate. It’s a useful mental model for why we should be deploying and running our own software rather than just writing it (I’m mostly missing this right now, and aim to change that over the next 6 months).

            Once you understand the terrain, Reilly notes, “The more you know the terrain, the easier it will be to bridge gaps by sending the email summary nobody is sending, introducing two people who should have spoken a month ago, or writing a document to show how projects connect to each other.”

            Vision and Strategy

            On creating technical vision, Reilly is pragmatic: “Writing technical vision or strategy takes time. If you can achieve the same outcome in a more lightweight way, do that instead.”

            When you do need to build consensus, she introduces the concept of nemawashi from the Toyota Production System—“sharing information and laying the foundations so that by the time a decision is made, there’s already a consensus of opinion.” Or as she puts it more directly: “Don’t call for a vote until you know you have the votes.”

            Time and Energy Management

            The chapter on finite time hit home. Reilly is refreshingly direct:

            “You have to make peace with walking past things that are broken or suboptimal (or just really annoying) and taking no action.”

            This isn’t permission to ignore problems—it’s recognition that at the staff level, choosing what not to work on is as important as choosing what to tackle. She encourages you to “understand what kinds of work are expensive for you, and what kinds will leave you with some smartbrain at the end of the day.”

            Before taking on a project, she suggests asking yourself: “Do any of the people you’ll work with leave you exhausted every time you talk to them?” It’s a practical filter I hadn’t considered explicitly before, but have certainly experienced.

            By this point in your career, “you will be largely (but probably not entirely) responsible for choosing your own work.” Part of that responsibility includes finding ways to “free up your resources by giving other people opportunities to grow, including starting projects and handing them off.”

            Leading Big Projects

            When facing a daunting project, Reilly offers reassurance:

            “The job here is to be the person brave enough to make—and own—the mistakes. You wouldn’t have gotten to this point in your career without credibility and social capital. A mistake will not destroy you. Ten mistakes will not destroy you. In fact, mistakes are how we learn.”

            Her approach to feeling overwhelmed is practical: “use your core muscles. If you’re most comfortable with code, jump in. If you tend to go first to relationships, talk to people. If you’re a reader, go get the documents.”

            On design work, she advocates for being concrete over being safe:

            “But it’s a better use of your time to be wrong or controversial than it is to be vague. If you’re wrong, people will tell you and you’ll learn something, and you can change direction if you need to.”

            And she’s firm about scope creep: “‘We might need it later’ is not a good enough justification.”

            For those worried about spending time coding at this level, she quotes another engineer: “If spending a day a week coding keeps you engaged and excited to come to work, you will likely do better in the rest of your job.”

            Unsticking Projects

            When blocked by other teams, Reilly emphasises gratitude and making things easy:

            “If someone goes out of their way to help you, say thank you. In companies that have peer bonuses or spot bonuses, there’s already a structure for saying thank you: use it.”

            Structure your requests so they’re “easy to say yes to, with as little reading needed as possible.”

            On migrations and technical debt, she’s direct about the impact: “The half-migration slows down everyone who has to engage with it. This is a place where a staff engineer can step in and have a lot of impact.”

            And remember: “there is no such thing as a temporary solution.”

            For documenting decisions, she recommends “Lightweight Architectural Decision Records for showing why you made the choice you did”. We noticed other teams at Canonical using these and considered adopting them, but decided against it for now.

            Being a Role Model

            The chapter on being a role model contains some of the book’s most quotable wisdom. On competence, Reilly writes:

            “Competence is built on knowledge and experience, but you also need to be able to apply those abilities. That starts with the self-awareness to know what you can do, how long it will take, and what you don’t know.”

            She pushes back against imposter syndrome: “Being competent doesn’t mean you need to be the best. I’ve sometimes seen tech people be shy about claiming to be an expert, because they can always think of someone in the industry who is better than they are. Don’t set your bar at ‘best in the industry.’”

            And crucially: “Admitting ignorance is one of the most important things we can do as tech leads, senior engineers, mentors, managers, and other influencers of team culture”. I have long pushed this myself, not only in these fields but as an educator as well. (Fascinatingly, it’s one area where current AI is terrible.)

            On standards:

            “Your standards will serve as a model for how other people work. Know what high-quality work looks like and aim for that standard in everything you do, not just the parts you enjoy most. Write the clearest documentation you can. Be the first person to know if your software breaks.”

            She emphasises that feedback makes your work better: “Your solutions are not you and they don’t define you. Criticism of your work isn’t criticism of you.”

            When someone brings you a problem, her advice is to “stay calm. Ask questions. Understand why they’re telling you. Do they just need to vent? Are they hoping you’ll take action?”

            She shares a story about making a production mistake early in her career and a colleague’s response: “It’s always interesting to see how new people handle their first screw-up. We’ve all been there.” Then she reflects: “Tim took the time to be kind.”

            On team dynamics, she reminds us:

            “While you may be the best coder on the team, the most experienced engineer, or the fastest problem solver, that doesn’t mean you should jump on all of the problems. You’re working as part of a team, not a collection of competing individuals. Don’t become a single point of failure where the team can’t get anything done when you’re not available.”

            Future-Proofing Your Work

            Reilly emphasises thinking ahead:

            “So take the time to leave your production environment, codebase, or documentation so that it just works for whoever comes along next. Write tests that will let you refactor your code without breaking things. Follow your style guide so that the people who copy your approach will also be following your style guide.”

            She warns: “Every time someone leaves your company, you lose institutional knowledge. If you’re lucky, you have some old-timers storing history in their brains. But eventually, inevitably, you’ll have complete staff turnover.”

            And on designing for the long term: “The system will never again be as well understood as it is on the day it’s created.”

            She quotes Martin Fowler: “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

            Teaching and Influence at Scale

            Reilly distinguishes between giving advice and actually teaching: “What’s the difference between telling people things and teaching them things? Understanding. When you’re giving advice, you’re explaining how you relate to the topic, and the receiver can take your advice or leave it. When you’re teaching, you’re trying to have the other person not just receive the information but internalise it for themselves.”

            For hands-on teaching: “Successful teaching includes hands-on learning and activating knowledge: the student should be doing as well as listening.”

            On delegation, she advocates for messiness:

            “your colleagues won’t learn as much if you only delegate the work after you’ve turned it into ‘beautifully packaged, cleanly wrapped gifts.’ If you instead give them ‘a messy, unscoped project with a bit of a safety net,’ they’ll get a chance to hone their problem-solving abilities, build their own support system, and stretch their skill set.”

            Before offering unsolicited advice: “Before you offer your thoughts, think about whether the other person is asking for them. Think too about whether you even have enough context to tell them something that’s both helpful and nonobvious.”

            And if you really want to share: “If you’re itching to give unsolicited advice on a topic nobody is asking you about, consider writing a blog post or tweeting about it instead.”

            Career Growth

            The final chapter acknowledges that specialisation often happens accidentally: “In fact, it’s easy to gain a specialty accidentally just because it’s what you’re doing at work: one experience leads to another, and next thing you know you have a specialization.”

            But she also normalises staying put if your current role is working:

            “If your job is giving you what you need, there’s no need to change anything. I want to emphasize that because our industry puts a lot of focus on changing jobs frequently, and the regular ‘new job’ announcements can make you feel like you should be moving too.”

            And success can mean different things, including working less: “Success can mean working less in your current role. One engineer I spoke with, Jens Rantil, swapped a staff engineering role for 80% time and a 20% pay cut at a much smaller company. As he said, ‘Every Thursday is a Friday! It’s amazing!’”

            On finding your next role, she quotes Graham: “I’ve found that people that know you well are always going to be the ones that find you the phase 2 roles that are ‘shaped like you.’ People that don’t know you are always going to offer you the job you just had”. I’ve experienced this, too.

            Small Touches I Loved

            • “I recommend playing Civilization to understand all things about staff engineering. Tell your boss it’s research.”
            • “Being the grizzled, experienced best supporting actor is an amazing role.”
            • “In general, if there are more people being the wise voice of reason than there are people actually typing code (or whatever your project’s equivalent is), don’t butt in.”
            • The clearest indicator of what a company values: “what gets people promoted.”
            • “Think of it as a Ship of Theseus: every individual component may get replaced over the years, but the fundamental system continues. It’s all metaphysical architecture.”

            Should You Read It?

            Yes. Whether you’re already a staff engineer trying to figure out the role, or an ambitious senior engineer wondering what’s next, this book provides both frameworks and practical tactics. Reilly’s writing is clear, honest, and grounded in real experience. She acknowledges the uncomfortable parts of the job—the politics, the ambiguity, the need to let some things stay broken—without being cynical about them.

            The book won’t give you a prescriptive checklist (staff engineering doesn’t work that way), but it will help you build better mental models for navigating technical leadership. As Reilly reminds us, by this level you’re largely choosing your own work—this book helps you choose wisely.

            (You can also see my full set of highlights if you’d like).

            2025 in Media

            (Post theme: friendly fire (the pool song)).

            This year, I watched 164 films. I recommend Tinā, KPop Demon Hunters, The Gorge, Swiped, Python: The Documentary, Girl Haunts Boy, and We Live in Time, and Sinners. A somewhat disappointing year for films for me.

            I also watched 1,259 episodes of TV. I recommend Taskmaster, The Runarounds, Murderbot, Department Q, and Shrinking. Not a great year for TV, either – a lot of stuff I’m somewhat interested in watching, but nothing that really grabbed me.

            On YouTube, I watched a lot more than in previous years. I recommend the Taskmaster Podcast, the TalkVille Podcast, Nikki Lu, Dish Podcast, and Off Menu.

            I listened to 158 hours of podcasts (this is roughly how long I spent travelling, since that’s about the only time I listen to podcasts these days). I recommend The Morning Shift, the Taskmaster Podcast (again), Gone By Lunchtime, Juggernaut, Wait Where Was I, and The Long Play.

            I listened to 3,158 songs (around 64,000 minutes) this year, up quite a bit from last year (mostly because I was living alone for most of the year – it is very quiet!). I recommend Kids Up The Tree, Cassie Henderson, fdasavage, aleksiah, Borderline, Little Green, Emei, Maddy Low, Fan Club, Phoebe Grace, Brooke Alexx, Daisy Grenade, Chloe Parché, and LØLØ. A really great year for discovering new music.

            I read a lot of stuff online (via RSS). I recommend everything I posted to tonyandrewmeyer.blog, and in particular: The Spinoff, Simon Willison, Armin Ronacher, and Charity Majors.

            I read 115 books (including paper, ebooks, and audio books) this year (a bit over 47,000 pages). I recommend The Staff Engineer’s Path: A Guide for Individual Contributors Navigating Growth and Change, most of Brandon Sanderson‘s books, The Thursday Murder Club, The Library Trilogy, The Witch Roads, The Final Architecture, and Violet and the Velvets: The Case of the Missing Stuff. A good year for enjoyable books, but missing anything that really wowed me, unfortunately. A good book club year again, and a good year of re-reading some childhood favourites (not all of which stand up).

            Happy new year!

            Review: Help! I Have a Manager! – Wizard Zines

            (Post theme: Talk by Coldplay)

            Next up in the Wizard Zines set is an odd one, not being particularly technical, and I think one of the earlier ones: Help! I Have a Manager, which is all about building good relationships with your manager.

            Like Julia, I’ve had several good or great managers, and a few not so much. I have found them all very different, so page 16, which is all about this, really resonated. Other than that, this was pretty much all advice I’d seen elsewhere and/or picked up naturally. For someone really early career, this might be worthwhile, but I’d skip it otherwise.

            Unlike the other zines, this one (at least the PDFs, when viewed in Apple Books) had weird spacing issues where text had odd gaps and sometimes had overlaid characters. Not enough to prevent reading the zine, but enough that it doesn’t feel polished like the others.

            Review: Bite Size Bash – Wizard Zines

            (Post theme: Hall of Fame (feat. will.i.am) by The Script)

            As mentioned previously, I purchased the set of Wizard Zines via my annual training budget, and am working through them. Current reading: Bite Size Bash.

            The first 20 pages surprised me – I don’t consider myself particularly knowledgeable in terms of bash (or similar shell scripting) but pretty much everything in the basics I’ve managed to somehow pick up over the last couple of decades, despite usually jumping pretty quickly into another tool whenever my needs get above simple. It is a great intro, though, and I would have benefited having this at hand years back.

            On page 20, parameter expansion is introduced. Most of this was either new to me, or I think I’ve seen but certainly wouldn’t remember to use. I’m not sure how to make this stick, though – the syntax is so odd. Maybe I should just jump to this page next time I’m writing bash, or maybe I’ll remember that it can be done and that will be enough to look it up or remember. I do wonder if LLM will replace this sort of learned syntax, though.

            After that, it was background processes and subshells, both of which were again surprisingly familiar. After that is trapping signals – I knew this could be done, but I’m pretty sure by the time I have something that needs to do this, I’ve already moved to another language, and I don’t see that changing. Errors and debugging were also mostly things I knew, except for ‘trap x DEBUG’, which seems pretty handy.

            Overall, this zine surprised me: I expected to learn a lot, and instead recognised a lot. In some ways, this is great: I feel more confident that I do actually know the most useful core of shell scripting (even though certainly not the vast area beyond that). I’d definitely recommend it for shell scripting beginners (especially bash) but likely not for others.

            Review: Become a SELECT Star – Wizard Zines

            (Post theme: Call Off the Search by Katie Melua)

            As part of my training allowance for 2024, I purchased all 14 of Julia Evan‘s zines. There are definitely ones I expect to learn from more than others, but having the pack appealed, and one of the things I really enjoy about her posts is finding little tidbits of information that I didn’t know, even though I would have said I know the topic fairly well in general.

            First up: Become a SELECT Star, which, as you’d guess from the title, is all about the SELECT statement in SQL. The first dozen pages are a really good summary of the fundamentals: things that I gradually absorbed over the last 20 or so years, and probably would have been better off with having a summary like this rather than a bunch of more traditional reference material.

            I really like how the examples work through the query in the logical order rather than the syntax order. It makes it much simpler to follow what’s happening.

            On pages 14-16, it covers window functions, which I didn’t really know at all. I would normally just do this by getting a bunch of the data down into something like Python and calculating there. I’m a big fan of moving computation left where possible, so these seems super useful, and something I hope I remember (although I don’t do a huge amount of SQL these days).

            The zine continues on to cover NULL and COALESCE, which we used a lot at SpamExperts, so those were pretty familiar, but again a good summary that I could have used many years back! It then covers CASE, and I don’t remember if I knew that or not, but also don’t think I can think of times I would have wanted it directly in SQL.

            After a straightforward page on counting rows, it moves into subqueries. I’ve used these quite often (I’ve often had situations where subquery performance was better than joining, for various reasons). However, common table expressions (naming sub queries) is new to me, and look super useful.

            It wraps up with a few more useful tips, most of which were things I already knew.

            I’d definitely recommend this to anyone that’s just starting with SQL. If you’re a SQL expert, it’s likely not going to be useful, but if you’re a casual querier like myself, then there are good tips to pick up, and given how small and inexpensive the zine is, I’d highly recommend picking it up.

            GitHub “sync fork” silently failing

            (Post theme: Oops! I Did It Again by Britney Spears)

            Posting because I’ve hit this three times now and each time not remembered the solution until I figured it out again, in the hopes that writing it down will prompt my memory next time and avoid a fourth “figure it out fresh” cycle.

            At work (in the team I’m on), we develop in the open using public Github repositories. To introduce a change, we fork the repo, create a branch, and submit pull requests to the upstream main branch.

            As changes make their way into main, it’s handy to be branching off an up-to-date fork, and GitHub has a convenient “sync fork” tool in the web UI to do this. Most of the time, this works perfectly. Unfortunately, a few times I’ve tried to sync and it silently fails (the cause is user error, but the silent nature of the fail is very poor UX from GitHub, and I feel like they could actually make the whole process work, which would be ideal UX).

            The reason it has failed (each time it has happened to me) is that branch protection is enabled for the main branch on the fork. I’ve enabled this to avoid accidentally pushing changes to main (forgetting to create a branch first), which I never want to do – except for pulling in upstream changes.

            There might be a simpler way to work around this (other than opening a PR from upstream main to the fork main) but I just disable the protection, sync, then enable it again.

            Mobile Phones at Mahurangi College – Feedback

            (Post theme: The Times They Are-A-Changin’ by Bob Dylan)

            This is a copy of the feedback I provided to Mahurangi College in response to this consultation request:

            The Government has introduced regulations that require all state schools to have student phone rules in use. Rules must be in use as soon as possible in Term 1 2024 and no later than Term 2.

            Many countries around the world have successfully banned mobile phones in classrooms, or are in the process of doing so. A solid body of evidence is emerging that supports the banning of phones in schools. 

            Our draft policy and notes are included here, as well as a space for you to provide some feedback.

            So far this term our approach has been to educate – students have had the rules clearly explained, and lots of reminders and warnings have been given. The vast majority of students have adapted very well.

            Following your feedback, we will finalise and publish our final policy.

            Mahurangi College, February 2024

            I understand that the requirement to have a policy has come from the central government, which puts some constraints on what the school can do. However, I had hope that the school would show more courage and defy poor decision making as much as possible. Given that ERO is responsible for monitoring the implementation of these policies, at worst the school would receive a negative comment in a rarely-read review, and by the time the next review cycle came around, it’s likely that a government less interested in pandering to racist, anti-science, scared, old people would be in power.

            Any form of defiance would suffice, but I like following the letter of the regulation rather than the intent. The iPhone is famously “an iPod, a phone, and an Internet communicator”, and Android phones are widely recognised as being functionally equivalent to iPhones. Students must not be allowed to use or access a phone – but there are no rules about iPods or internet communicators. The answer is clearly that the Phone app on mobile devices must be banned, but using the rest of the device is fine (you could even use a device management profile to disable the Phone app while at school).

            This is logically consistent, since students are not only allowed but expected to have other digital devices (such as a laptop), which has exactly the same internet communication functionality (indeed: the permitted smart watches, laptops, tablets, and other devices are essentially the same device as a phone – often running variants of the same operating system on the same chips – just in a different form factor).

            Under no circumstances should phones be used to photograph or film any student or member of staff without their permission, or to film any fights or skirmishes.

            Mahurangi College Draft Policy

            For the record, I have no objection to this as a policy statement, although I would suggest that it’s mistakenly placed in a “mobile phone” policy, given that there are many other devices (and a class that is specifically focused on learning how to use them well) that are capable of photographing or filming a student, and the choice of device is entirely irrelevant.

            • Headphones & earbuds also cannot be used at school (apart from on buses) as they require connection to a mobile phone.
            Mahurangi College Draft Policy

            It’s hard to believe that this passed any sort of quality control. Did you have a junior student write it? I would expect that anyone old enough to work at the school would be familiar with a multitude of devices with which headphones (whether in earbud form or otherwise) can be used. Perhaps the staff might remember using headphones with a record player, Walkman, or Discman? Perhaps some of the staff are familiar with the school’s own requirement that students do have headphones so that they can consume media during class without disturbing other students? Was the author of this policy aware that the school offers classes in music, dance, and media studies, and that film is studied in many of the English classes? Did they know that the laptops that the school requires students have almost universally work with headphones? Given the conflicting policies, which one wins out?

            Perhaps you’d consider looking at the actual science? For example, a 2023 study that showed that students using smartphones outperformed those without (Wang, J.C., Hsieh, CY. & Kung, SH. The impact of smartphone use on learning effectiveness: A case study of primary school students. Educ Inf Technol 28, 6287–6320 (2023). https://doi.org/10.1007/s10639-022-11430-9), or the Harvard Graduate School of Education who say that more thought needs to be applied rather than simple bans. Closer to home, Massey University educators clearly state that bans are not the right choice. Or look at meta-studies (for example: Calderón-Garrido, Diego & Ramos-Pardo, Francisco & Suárez-Guerrero, C.. (2022). The Use of Mobile Phones in Classrooms: A Systematic Review. International Journal of Emerging Technologies in Learning (iJET). 17. 194-209. 10.3991/ijet.v17i06.29181), which show benefits in the use of phones at school.

            It should be obvious that the ability to have at hand a device that is a calculator, a compass, an e-book reader, a still and video camera, a research tool that would be considered magical even a few decades ago that provides access to nearly all the world’s information, that tracks and provides advice for improvement of health, a torch, a measuring tape, a glimpse into virtual and augmented reality, that receives emergency alerts, and much more is of huge value to a student. Instead of harming their educational development (and providing an environment irrationally different from the world they will enter at the conclusion of secondary school) you should be figuring out ways to make sure that those students who do not have phones are able to use one.

            I have no objection to behaviour management, whether during class time or during breaks on the school property or on school trips. If someone is misusing a phone – or anything else – in a way that disrupts their or other students’ learning, then that should be remedied appropriately.

            I’m also tolerant of prohibiting access to specific internet properties (TikTok, Instagram, Snapchat, and so on), although I do believe that in time prohibition will be demonstrated to a poor approach to the problems that these sites exacerbate.

            I have no hope at all that the school will reconsider this policy (although a little hope that someone will realise that headphones can be used with devices other than phones), particularly given the numerous other policies that are clearly either anti-learning or irrelevant to learning. However, I offer this feedback anyway, so that at least you will have heard how wrong you are.

            Writing as a metaphor for coding

            At work, our book club is reading Code Complete, and had our first discussion session today. I first read this in early 2011 – roughly 6 years into professional software development – and remember thinking quite positively of it at the time. We’re only three chapters in, but I’m decidedly more mixed on it this time around – I’ve had a lot more varied experience with development projects than in those early years, and a lot of the book lands quite differently (I do suspect that the later chapters will have stood the test of time better).

            The second chapter of the book is focused on the importance of choosing a metaphor for software development – it ends strongly suggesting that building construction is an elegant metaphor. I agree that metaphor can be useful (but is also easily overused, and people get fixated with the imperfection of the chosen metaphor – “But if you extend them too far or in the wrong direction, they’ll mislead you”, as the author says) and that construction can work as one for software development.

            However, the author, says:

            For an individual’s work or for small-scale projects, the letter-writing metaphor works adequately, but for other purposes it leaves the party early—it doesn’t describe software development fully or adequately.

            Steve McConnell, Code Complete, Chapter 2 “Software Penmanship: Writing Code”

            This struck me as deeply ironic. Writing is an excellent metaphor for software development, and the author of a book – especially a large technical one – should be extremely aware of this.

            The author seems to only consider the analogy of the metaphor to be of “writing a casual letter”, rather than writing in general. This is unfair to the metaphor and not applied to that of construction (which covers all sizes, not just flat-pack assembly). Writing ranges from a succinct social media post to a collection of textbooks or connected story that ranges over dozens over books by multiple authors (Wild Cards, Cosmere, Marvel, Riftwar, to name a few). This is hardly unique to writing – construction, farming, and other metaphors the chapter explore all range in sizes.

            Writing is usually a one-person activity, whereas a software project will most likely involve many people with many different responsibilities.

            Steve McConnell, Code Complete, Chapter 2

            This quote was particularly interesting, as one of my colleagues brought it up in our discussion as an example of how McConnell was correct about writing being a poor metaphor, whereas I read it as an example of how wrong he was.

            The “many people with many different responsibilities” absolutely applies to (non letter!) writing – you have editors, alpha and beta readers, illustrators, publicists, and many more. A lot of these work well in the software development metaphor – early readers are code reviewers, illustrators are designers, publicists are, well, publicists, and so on. This is the aspect that I was focused on when I read it.

            My colleague, however, saw the truth in the “one-person activity”. It’s true that a lot of writing is done by one person. There are a lot of examples where this is not the case (co-authoring, anthologies, shared universes, ghostwriting, a lot of journalism, etc), but it’s probably safe to say that there’s less cowriting (particularly of the same block of text, however you define “block”) in code than other writing. I think where we differ is that I see this as one area where the metaphor is weak, but the rest is so strong that it outweighs that.

            I also do suspect that that there’s an awful lot of software that is written by a single person. This isn’t just sole-developer products, but also components of large, multi-person, systems where there’s a single person that does nearly all the writing and maintenance of that one component (or module or library or micro-service or …). This isn’t good software development, but in my experience it is, unfortunately, fairly common. Often there are other people involved, but only lightly, in the same way that an editor or sub-editor might be with other writing.

            In writing, a high premium is placed on originality. In software construction, trying to create truly original work is often less effective than focusing on the reuse of design ideas, code, and test cases from previous projects.

            Steve McConnell, Code Complete, Chapter 2

            I’m not sure that originality is that much of a premium in letter writing – but then I never did much of that. More broadly, originality has a “premium” in some forms of writing, but not in others – people are generally looking for the same broad style in a new romance novel, they find it easiest to read news articles that are structured in the same way, the latest Reacher novel is not that different from the previous one (or the last Will Robie, or the last Alex Cross, and so on)1.

            There’s a concept in software development that you get three “innovation tokens”. Similarly, when writing a novel or series of novels, you can have a truly original character, or world, or plot, or theme, but you almost always need to have the majority of the work be fairly familiar to the reader (particularly a reader who is familiar with the genre). Just as with software development, you can go wild with innovation and originality, but it’s high risk and makes it harder for readers/users.

            When you finish writing a letter, you stuff it into an envelope and mail it. You can’t change it anymore, and for all intents and purposes it’s complete.

            Steve McConnell, Code Complete, Chapter 2

            This is true of a letter, but untrue of most modern writing. Pushing the irony more, this is a quote from the second edition of Code Complete. Writing that ends up in print often is in a final form – but there’s also a lot of software out there that just runs without any updates.

            To be fair to McConnell, 30 years ago there was a lot less revision of writing – no editing Wikipedia, pushing out ebook updates, rapidly revised news articles, or tweaked blog posts. On the other hand, there was also a lot of “finalised” software back then too, where you’d buy a box with a disk or cartridge and, unless you did buy an updated version, you’d have that same version forever.

            But extending the metaphor of “writing” software to a plan to throw one away is poor advice for software development, where a major system already costs as much as a 10-story office building or an ocean liner.

            Steve McConnell, Code Complete, Chapter 2

            I’m very much in favour of a reasonable level of well-executed planning and design, but beginning a software project without being willing to throw away any dead ends would strike me as a huge red flag. Defining the role of a software architect is complicated (see also this great Charity Majors post) but I maintain that the core task of an architect is working with people to minimise the number of decisions that are regretted in the future. That might be a wonderful design where almost nothing is thrown away. It might also be settings things up so that throwing things away is inexpensive and experimentation leads to market success.

            I’d argue that with the really huge projects, we have plenty of examples (Novopay, INCIS, and others just in Aotearoa New Zealand) that show that big upfront planning with a reluctance to throw anything away leads to terrible cost overruns and missed deadlines.

            Building software implies various stages of planning, preparation, and execution that vary in kind and degree depending on what’s being built.

            Steve McConnell, Code Complete, Chapter 2

            This is exactly what writing is like. Just like when writing a small “throw-away” software script, almost no planning goes into a social media post. When writing a novel, there’s a huge amount of planning, preparation, and execution (here’s a series going into it from one author – there are many, many, others – books on how to write books are almost as common as podcasts about making podcasts!). I find it difficult to believe that this was not the case for writing Code Complete itself.

            McConnell extends that argument to compare the cost of making a mistake on a small project with one on a large project (ignoring any learning that may have come from making the mistake) – this equally applies in writing. If I end up rewriting a section of a blog post, that’s fairly trivial. If I have to restructure the entire third act of a novel, that’s a bigger issue, and if I have already finished two books in a trilogy and need to make changes to them to make the final volume complete, that’s very expensive to fix.

            In building a house, you won’t try to build things you can buy already built. You’ll buy a washer and dryer, dishwasher, refrigerator, and freezer. Unless you’re a mechanical wizard, you won’t consider building them yourself. You’ll also buy prefabricated cabinets, counters, windows, doors, and bathroom fixtures. If you’re building a software system, you’ll do the same thing. You’ll make extensive use of high-level language features rather than writing your own operating-system-level code.

            Steve McConnell, Code Complete, Chapter 2

            When writing a novel, you don’t start from first principles. You’ll probably have a three-act structure, your story probably fits – at least somewhat – into one of seven basic plots, and you’ll build on top of whatever tropes are appropriate to the world you’re writing about. You don’t need to explain enemies-to-lovers or the misdirects in a mystery story, and you can call your Hobbits “halflings” and most readers will immediately have the right characteristics to mind. Just as in McConnell’s example of luxury housing having some of these fittings custom-made, the highest quality novels often deviate from the norms in a few specific areas (an imaginative magic system, a innovative take on local history, an unusual prediction about the future, and so on).

            Finally, the construction analogy provides insight into extremely large software projects. … [Builders] build in margins of safety; it’s better to pay 10 percent more for stronger material than to have a skyscraper fall over. A great deal of attention is paid to timing. When the Empire State Building was built, each delivery truck had a 15-minute margin in which to make its delivery. If a truck wasn’t in place at the right time, the whole project was delayed.

            Steve McConnell, Code Complete, Chapter 2

            Cost and timing are important in extremely large writing projects too. Delays in editing or proofing or illustration or printing or many other things can delay an entire book launch (the Potter books have apparently reached nearly US$8B in sales, the Empire State Building cost under US$1B to build, adjusted for inflation). When a book is very high profile, it’s worth spending extra to have additional early readers and editors, just as you build with stronger material (obviously an unsuccessful book is less significant than a collapsing building).

            Overall, I do agree with some of the core takeaways of the second chapter – that there’s value in metaphor, that they are “a little sloppy”, and that you should use the best (mix) of metaphors that work in the context. I just can’t agree that construction is a better metaphor for writing code than writing (non-code) is.

            This chapter might have hit the sweet spot for me – the combination of reading/writing and software development – but I’m hopeful that the upcoming ones will also be as thought-provoking and enjoyable to discuss with my colleagues. If you don’t have a work book club, I highly recommend starting one! (Non-work book clubs are great too!).

            1. To be clear: I really enjoy a good romance novel and all of the book series listed there. The familiarity has the same comfort as a good TV procedural or film sequel. ↩︎

            Inconsistent public service efficiency

            (Post theme: drivers license by Olivia Rodrigo)

            I renewed my driver’s license last week (having turned 45 recently) and it was striking how different the experience was to the other common government-issued identification: a passport. New Zealand’s passport service, Te Mata Uruwhenua, (run by Te Tari Taiwhenua the Department of Internal Affairs) is remarkably efficient – everything from the application process through to delivery is handled extremely well. They promise reasonable process times, and almost always better them.

            Last Friday, on the other hand, despite arriving less than 15 minutes after they opened, I had a 30 minute wait for someone to spend less than five minutes reviewing a form, take a photo, and provide an image of a signature.

            There are a lot of flaws in the system, such as:

            • Why not have the form available online? Presumably someone is going to be entering the relevant details into a digital system anyway. The passport renewal process is entirely digital.
            • What benefit is there in requiring physical possession of the expiring license? They have all this data in the system, obviously, so if they wanted to check that I looked like the 10-year-old photo, they have that already. No-one checked my signature. Having the card doesn’t prove identity – I could have picked it up off the street. I didn’t have to go anywhere or show my old passport to renew it. Sadly, an elderly lady in front of me in the queue, who had travelled almost an hour to get there, had forgotten her old license and had to get rejected at the counter.
            • Why take the photo there rather than just providing one? That works for passports, where the requirements are much more strict. This could easily be part of the submission process.
            • I’m not particularly convinced that the written signature provides much value, but even if it’s needed, this is done on some sort of digital system anyway, so could also easily be done as part of a submission.
            • My expiring license was invalidated (it had about 6 weeks left) and replaced with a paper temporary license that lasts for 3 weeks (which will be tight to get the new one in the post, but that’s a separate rural post issue). Why not just leave me with the old one until the new one arrives?
            • Why is someone manually checking a form anyway? The address checks were making sure they matched the ones on file (both inaccurate anyway, with the regular address wrongly including the rural delivery number, and the mailing one not matching the form NZ Post likes), which is trivially automated. The other details would similarly be simple to check by a system.

            It’s strange to have one service work so well and one so poorly but easily improved. Can’t we just loan some people from Te Mata Uruwhenua to Waka Kotahi NZTA to get things improved?