Conway's Law, reviews' scope, and dev process maps 💡
Monday Ideas — Edition #129
🎯 Sleuth — alignment at all levels
When priorities change, here's a simple process every engineering leader should follow:
⚖️ Re-align — on goals and re-allocate resources as needed.
📣 Communicate — the change to the team, or the entire org.
🔍 Monitor — check if everyone is rowing towards the new direction.
This week I am happy to promote Sleuth, which makes this whole process easy.
Sleuth is a long-time partner of Refactoring, and it helps leaders align at all levels of management. Find out how 👇
1) 🏯 Conway’s Law
Consider Conway’s Law on organizational design:
Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization's communication structure.
The consequences of this rule are non-trivial.
Most notably, that changing your system architecture most often requires changing your communication structure as well — and vice versa.
For example, it is hard to organize your team into small, independent units, if your software architecture is a monolith. People will likely step on each others toes.
Likewise, you won’t probably get the full benefits of microservices as long as your team stays a single large unit. The overhead brought in by orchestration, observability, partitioning, and more, might not be worth it if you don’t get the upside of distributed, autonomous teams.
2) 🔍 Code reviews should be ever-shrinking
If code reviews are the feedback loop of your development process — what should they give feedback on?
In most teams, there are many devices that impact how you write code, but let’s simplify and look at two particularly relevant ones in this context:
📋 Design docs — that’s where you discuss your design and implementation plan. You may follow a template that enforces good practices.
🤖 Static analysis — that’s where you catch coding standards violations, security vulnerabilities, missing tests, and various kinds of smells.
Design docs are about things you discuss before you write code, while static analysis happens after you have written it.
These steps can intercept many items that would otherwise be firmly within the scope of code reviews. So, ideally, you want most of the action to happen in these two stages, as opposed to reviews, with the latter acting as a fallback.
In fact, 1) you don’t want reviews to deal with design issues, as they are expensive to rectify after you have already written the code, and 2) you obviously don’t want human reviewers to look for issues that can be found automatically.
Static analysis tools can do 2 things really well IMO:
Boring easy stuff like aligning brackets and single-to-double quotes (we’ve just added a button into our UI that will allow you to generate a patch for all open issues like this in your codebase at once!)
Obscure things that not everybody understands (and thus potentially missed in code review) — a lot of security stuff is like this, for instance not generating a non-http-only cookie — you only know if you know!
— Kendrick Curtis, VP of Engineering at Codacy
Design docs and static analysis don’t cover it all, nor are they ever perfect, but by investing in them you can shrink what goes into code reviews considerably, and address many items arguably in better ways — by either automating them, or shifting them left.
So, one of the goals of code reviews should be to continuously reduce their own scope, by allowing engineers to uncover items and rules that can be later enforced by other parts of the dev process.
More hot takes on code reviews below 👇
3) 🗺️ Map out your development process
A few months ago I interviewed Malte Ubl, CTO at Vercel.
As you would expect, we talked a lot about developer experience—which is Vercel’s (and Malte’s) bread and butter.
Among the various tips, Malte recommends writing down the entire development process as a one-dimensional flow.
This exercise helps identify each step in the process and potential bottlenecks. By mapping out the journey from planning to production deployment, teams can pinpoint areas for optimization and improvement.
This process starts with local development, for which Malte says you should aim for near-instant feedback, ideally around 50ms. The rapid feedback loop allows developers to see changes in real-time as they type, significantly enhancing productivity.
Malte also emphasizes minimizing the time between code push and preview availability, as this impacts how developers context-switch and manage their workflow.
We also discussed pairing this with safety net tools, like instant rollback and bisecting, to help improve productivity.
You can find the full interview below 👇
Last but not least! We are running a big survey about how engineering teams use metrics to improve their practices. You can help us below 👇
We are also giving away 20 paid memberships for free ($150 each!) 🎁 to people who answer the survey! We will draw the winners next month
And that’s it for today! If you are finding this newsletter valuable, consider doing any of these:
1) 🔒 Subscribe to the full version — if you aren’t already, consider becoming a paid subscriber. 1500+ engineers and managers have joined already! Learn more about the benefits of the paid plan here.
2) 🍻 Read with your friends — Refactoring lives thanks to word of mouth. Share the article with your with someone who would like it, and get a free membership through the new referral program.
I wish you a great week! ☀️
Luca
This is a nice read. What would one dimensional design doc look like?
Great teams learn to let static analysis do the heavy lifting, freeing human eyes for true craftsmanship.