Your First Steps to Writing Code That Doesn't Haunt You
How to dodge developer nightmares in 3 steps, and why maintainable code matters at the start of your career.
Hey there,
Like Jason Voorhees, your first professional code is going to hunt you down.
You’ll see it at night, as you tuck yourself comfortably into bed. There, in the corner of your eye. The class you wrote, pressured on time, approaching you, knife in the air, pointing downwards toward you.
“EXPLAIN WHAT I DO, IN A MINUTE OR LESS!” it screams.
You panic.
You can’t explain it.
The naming seems to make no sense.
You can’t seem to figure out the formatting.
The code does so much more than it should be doing.
“TIME’S UP, BUCKO,” the class screams.
The knife slices through the air.
You’re jolted awake
Luckily this isn’t real, right? It was just a dream?
The moment when the past catches up to you
Every junior developer I've met has that moment of dread.
They open a project they wrote months ago and feel pure confusion.
Lines that once made perfect sense now look like they were written in the language of the gods. Spaghetti code that tangles itself into impossible knots. Time ticking frustration growing.
It’s the kind of technical debt that makes senior developers shake their heads and junior developers want to delete everything and start over.
I recently spent quite a while refactoring an old class to retrieve some data from the database. The way it got the data, the joins it made, the naming. Everything seemed to be designed with the sole purpose of confusing the one reading it.
The problem wasn't their coding skills. It was that their original code was so tangled, trying to fit it into my limited brain almost made it explode
Three steps to avoid that moment
Let's talk about writing code that future you will actually thank you for, instead of code that makes you want to change careers.
Maintainable code is the secret weapon that'll make you stand out in your early career.
Why Maintainable Code Matters:
It makes you look like a pro (even when you're still learning)
Saves countless hours of future debugging
Shows employers you think beyond just "making it work"
If you're a new developer drowning in imposter syndrome and desperate to write code that doesn't make you cringe later, then here are 3 steps you can focus on:
Document like your future self is watching
Keep functions small and focused
Embrace consistent formatting
1. Document like your future self is watching
Comments aren't just for complex algorithms (or restating the obvious).
They're core tools for understanding.
Write the "why", not just the "what".
Imagine the scenario I talked about earlier. You’re woken in the middle of the night, and threatened. What would you love to know at a glance?
Practical steps:
Add a brief comment explaining the purpose of complex functions
Use clear, descriptive variable and function names
Write a short docstring explaining inputs, outputs, and any side effects
Document important assumptions and edge cases
Include examples for non-obvious implementations
Here’s an example of where the documentation for a function is lacking:
And here’s how it might be updated to be more descriptive:
2. Keep Functions Small and Focused
A good function is one that does what it says.
And it should do that thing well.
A way to find out if you’re doing too much in a function is to try and describe it. Did you use the word “and”? Why did you need to?
Practical steps:
Aim for small functions, but don’t go completely overboard
If a function is doing multiple things, break it into smaller functions
Use meaningful, verb-based names that describe the action
Follow the Single Responsibility Principle: Gather together the things that change for the same reasons, separate the things that change for different reasons
Test your functions in isolation
Here’s a function that does way too much:
Let’s revisit it:
3. Embrace Consistent Formatting
Consistency is more important than your personal style.
Nobody wants to work with a developer too obsessed with their own opinions, ready to argue anyone and anything about things that should just be agreed upon.
Talk to your team.
What’s the style you’re following?
The whole codebase can look like ti was written by one person if the team agrees on one style and consistently implements it.
Isn’t that more important than arguing semantics about formatting?
Practical steps:
Create a style guide for your team or personal projects
Set up automated formatting in your IDE
Use platforms that can do automatic reviews of code to ensure styles remain consistent
Try this today
Pick ONE of these principles and keep it top of mind in your next project.
Just one.
Start small.
You’re not fighting off Jason yet.
I recommend beginning with consistent naming conventions.
It’s like turning on the lights in a dark room.
The shadows aren’t that scary anymore.
Start by:
Picking your language's official style guide (PEP 8 for Python, for example)
Setting up an auto-formatter in your IDE
Renaming just one badly-named variable or function in your current project
See you next Tuesday!
As long as Jason doesn’t get you.
PS... Enjoying this newsletter? Consider referring it to a friend who's also navigating the start of their career! Each new subscriber helps us create more in-depth newsletters.