There's a term I like: 'innovation theatre'. It's used to describe when a business does things that look like innovation but really aren't. Hackathons with no real meaning, giving someone a title like Head of Innovation. It's usually big corporate companies trying to look cutting edge and impress people who don't know the difference.
There's a pattern I've noticed recently that's similar: ‘engineering theatre’. I’ve noticed this pattern is in projects built mostly by AI, driven by someone who’s off the engineering.
Some examples of the theatrics I see are:
- tests that don’t test anything meaningful but exist because 'good engineers test'.
- comments that don’t tell you anything but exist because 'code should be documented'.
- functions that do little to aid maintainability, one line functions that look like structure but add nothing.
- 500 line readme files littered with prose and emojis.
All these things look like engineering and are probably found in plenty of teaching material for engineers. What makes them theatre is the fact they’re being dished out to tick a box.
Coding agents really like to repeat patterns. In the vast amount of training material that makes up their corpus there are a lot of tests, comments and idioms. Without guidance, these agents will repeat these patterns liberally.
Agents aren’t copying verbatim from other sources (hopefully), that would be too obvious. Instead they apply patterns adapted to your project but with a strong bias to create. Every prompt adds comments, tests and more lines and emojis to the readme.
Much of this is an artefact of how LLMs are trained and rewarded. It is much easier to add training examples where the desired and rewarded outcome is 'add a comment and test alongside your change'. These lessons are not inherently bad, its the poor application of them that causes issues.
Much like innovation theatre, engineering theatre can be corrected when managed by someone who can call out theatrics. After all, both are an attempt to do something that can be valuable, just poorly applied.
Innovation theatre should be replaced with a proper strategy, one you'd happily execute if you were forced to keep it a secret.
Engineering theatre can be offset in much the same way, by putting the rules and frameworks in place to add tests or comments when it helps and remove them when it doesn't.
I alluded to it before but most of this behaviour is default LLM behaviour. It’s what shows up when there’s nothing else in place to guide the models. There’s probably information in the system prompt about comments and tests but because they need to be universally applicable they’re going to be high level. "Add comments and tests to code" is correct high level advice after all.
Your job as a user of these tools is to refine the guidelines. Agents are, for the most part, pretty good at following instructions. I’ve been slowly building a few hand written guidelines around comments and tests. They’re nothing special and the exact wording is mostly my personal preference but some simple things like:
- Default to no comments. New comments have a high bar.
- Assume the reader is a competent developer, don’t say things that the code tells us.
- Tests should be judged with the bar of ‘if we had zero tests today, would we add this one’.
- Consolidating several tests into fewer, more robust test is a good outcome.
- Tests and comments should be evergreen, they’re not there to justify choices or paint the narrative.
You’re welcome to copy these but what I think is more important is the process that led to them.
Real engineering, the nontheatrical kind, is about refining a process. You might not read every line of code but you observe the patterns, observe the system. If something seems off, question it. If something seems excessive, ask if it can be simpler. Write down what you observe and build on it.
The other side of this is matching your level of engineering to the project.
If you’re writing a silly throwaway website you are allowed to care less about how well it is engineered. That is also engineering. You can be accepting the theatrics and let agents write useless tests and comments in those scenarios because the additional effort isn't going to pay off.
If you're building something you want to be used by others, possibly even in exchange for money, then your engineering standards should be higher. The work to craft good software still exists even in scenarios where most of the code is written by AI.