5 engineering dogmas it's time to retire
A few months ago, I wrote about 13 software engineering laws, which are observations about how software projects behave.
Today, I’ll cover 5 practices that are considered ‘common wisdom’, and why I think worth reconsidering them.
Don’t reinvent the wheel - find a package
Every PR must be reviewed
2-4 week sprints are how modern teams work
Every code change should be behind a feature flag/gate
If a comment is needed, the code is too complex
1. Don’t reinvent the wheel - find a package
Why waste time writing code that someone already wrote before you?
The CTO of a startup I worked at hated dependencies. We worked with some 3D calculations (software for drones), and he was writing tens of mathematical functions himself. He insisted that even though it’s slower, he at least understands every part and can fix any bug that will pop up, and wouldn’t depend on anyone else for critical parts of our software.
I used to make fun of that paranoia, and he sent me to read some crazy stories:
The developer of left-pad took it down from NPM, breaking the builds of Facebook, Spotify, Netflix, and many more. It’s basically an 11-line for loop that adds spaces to a string.
The is-even npm package has 160k weekly downloads(!). The author published it back when he was learning to code. Here’s what it does:
You are also much more vulnerable to security incidents (and need to spend a significant amount of time chasing updates). In most smaller companies, there is no vetting process for packages (unlike for vendors) - every engineer does as they please.
With LLMs, it’s easier to both get into this mess and get out of it: it’s much easier to install an unneeded dependency by mistake, but it’s also quicker to implement ‘known’ solutions from scratch.
It’s a tricky balance.
Another ‘common wisdom’ among software engineers is that project management software sucks. It’s a necessary evil you just have to deal with.
I also thought this was just part of my job - spending hours chasing engineers to ‘keep the tickets updated’, so I could understand what’s going on and make better decisions. Switching to another tool felt like a huge project that was just not worth it.
Linear took that to heart, and made switching super simple with a 2-way sync, keeping your legacy tool updated.
I haven’t met an engineer who tried Linear and didn’t like it. Teams that switch to Linear see 2x more reported issues - engineers actually want to use the tool. More visibility => fewer meetings => happer engineers.
Thanks Linear for supporting today’s article!
2. Every code change must be reviewed
In every company I worked for in the last 15 years, we had mandatory code reviews (at least one, usually two reviewers per PR).
A couple of months ago I wrote a deeper dive about the price of mandatory code reviews.
In short - they help you improve the quality, but slow you down significantly.
I’m definitely not against code reviews - there is a TON of value in them. What I am against is a lengthy process with strict rules (like having to re-request a review for every commit at a PR, even after it was approved).
I love the process at Pylon: engineers merge their own code and only request reviews if they need input, think they have a risky change, or are still onboarding. Their thought process is: if we hire skilled engineers and trust them, there’s no reason to bottleneck every change with mandatory reviews.
Pair programming is also a great alternative to async reviews.
3. 2-4 week sprints are how modern teams work
I believe that sprints are taking the joy out of building software.
If you had to think about the ideal way to organize your team’s efforts, do you honestly think you would have gone with the current way of doing things?
Do you feel it brings the most value to your customers? Do you think your engineers truly enjoy the process, feeling they contribute from their own creativity?
Shape Up is a great alterinative. Here’s the gist of it (from here):
We work in 6-week cycles. Once a cycle is over, we take one or two weeks off of scheduled projects so everyone can roam independently, fix stuff up, pick up some pet projects we’ve wanted to do, and generally wind down prior to starting the next six week cycle.
Note: These are not sprints. I despise the word sprints. Sprints and work don’t go together. This isn’t about running all out as fast as you can, it’s about working calmly, at a nice pace, and making smart calls along the way. No brute force here, no catching our collective breath at the end.
My point is not that you should adopt Shape Up.
It is that there are alternatives to Scrum/Kanban. You can build a way of working that actually fits your team and company, without leaving everyone exhausted.
4. Every code change should be behind a feature flag
In many cases, feature flags are ruining your codebase:
Once you introduce the feature flags capability, PMs will come up with other ideas for using it:
Why should we rely on developers for the configuration change? Let’s move it to somewhere the PMs can access, and then we’ll be able to do it without bothering anyone.
While we are at it, let’s also make it adjustable per user! That way, the PMs can safely release the feature for a couple of users to gather feedback and test it themselves, and only afterwards release it to everyone.
This is similar to a Canary Release. The difference between them is that a Canary Released feature is exposed to a randomly selected cohort of users while here, the feature is exposed to a specific set of users.
And why limit ourselves to using it for turning features on? Let’s put the most resource-heavy feature behind one, and let the Ops people turn it off in case of an unusual overload.
Oh and we have those premium users, let’s have some features enabled only for them!
One last thing - you can put everything under a feature flag, right? So let’s not risk any changes without it, please hide any bug fix under a flag, in case the fix needs to be reverted.
Thus you find yourself in deep shit, with hundreds of active feature flags - making your codebase more complex and much harder to test.
Feature flags also give you a sense of false security - I’ve seen multiple bugs caused by developers releasing to production code that was supposed to be hidden behind a flag, but wasn’t (especailly in React).
I definitely think you should use feature flags - just not abuse them. It’s ok to just properly test a code change on staging and release it without any flags/gates.
5. If a comment is needed, the code is too complex
The V1 of commenting advice was: “Comment your code so it’ll be understandable by whoever comes after you”.
Then, the V2 version of the advice gained popularity: “If you need to add comments, it means your code sucks. It needs to be self-explanatory”.
Any extreme doesn’t make sense imo.
Yes, you can write code that will require fewer comments.
Still, in some cases a line or two can save someone else hours of frustration a couple of years in the future.
Final words
There are many other ‘common wisdom’ bits, like ‘don’t release on Friday’ and ‘microservices help with scale and ownership’.
None of them, and of the 5 covered in the article, is complete nonsense. There is a reason they became so common.
My point is that good Engineering Managers know to balance such dogmas with reality and constantly assess what’s best for their teams.