Last week we ran into the perfect example of how utils-based code will smack you over the face at the worst moment. So much time wasted. But a nice refactor in the end.
We have a lot of utils code, you see. There's payment utils, email utils, user utils, all sorts of utils.
Utils on utils
This doesn't sound so bad. Code is grouped together based on what it does. When you need payments, you go to payments utils. When you need emails, to emails. Makes sense right?
Now, where do you find the payment confirmation email?
🤔
In the email utils! Bit weird but okay, it is an email.
And here I've set a trap: Payment and email utils now depend on each other. Creating a payment sends an email and that email needs payment utils to figure out its content.
This is circular but it works. Python can figure it out.
Circular imports go boom
Then one day you want to send an email from a new place. You add a function to email utils, add an import, and boom 💥. Everything breaks.
Your code imports user utils which imports payment utils which imports email utils but your code also imports email utils which is not yet initialized and python gives up.
Python is an interpreted language (with caveats) and needs to read files start to finish to know what's in there. When it encounters an import of the same file while interpreting said file, it cannot know if the function you want exists.
The solution: Vertical modules
The problem with utils is that they agglomerate code. You see a horizontal slice across your codebase and go "Ah yes an email, email utils!"
But ask yourself: What is the email about? Yes it's an email. But what does it say? Why does it exist? Who is it for? What makes it go?
This is the actor-event-comand triplet from domain modeling. Who, what, why?
Put everything about payments in the same module. Including the email! Put your new things in their own module. Including the email!
Then keep a library full of atoms for self-contained low level operations like "send email to these addresses with this content".
Cheers,
~Swizec
Continue reading about Why utils are bad, an example
Semantically similar articles hand-picked by GPT-4
- Common abstraction traps
- Unit testing is for lazy people
- Smart core, thin interfaces
- Build the abstraction first
- Django protip #1: A better App structure
Learned something new?
Read more Software Engineering Lessons from Production
I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.
Subscribe below 👇
Software Engineering Lessons from Production
Join Swizec's Newsletter and get insightful emails 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.
"Man, love your simple writing! Yours is the only newsletter I open and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"
Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.
Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.
Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.
Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev
Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization
Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections
Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog
Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com
By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️