7 Steps to Reduce Code Smell đŚ¨
Dan is the founder of Tellspin, an on-call scheduler in Slack for DevOps and developers (https://tellspin.app). Helping workspaces reduce their contact footprint, resolve incidents faster, and regain deep focus.
Code smell is a way to describe code that hasnât aged well and has the potential for a lot of issues.
It usually is the source of a lot of hot fixes or workarounds keeping it functional. My most common reflex is to rewrite it. However, if Iâm not careful, Iâll waste an entire day and not improve anything.
After a decade of programming, here are my 7 steps to reduce code smell gradually.
Step 0: Admit there is a problem
I start to recognize my code is smelly when I start saying things like âthat time only took an hour.â
Iâm usually doing something simple, like adding another field to a form or another schedule for a customer. I quickly add in code because it feels like the easiest thing to do and ship the feature. There are so many other things on my plate, I donât have time for this, Iâll say to myself.
By the 5th or 6th hour Iâve hacked the same spot, I realize, had I rewritten it sooner, I would have actually saved time.
Step 1: Identify spots to clean
Smelly code is so disorganized.
Is it really smelly or do I just not understand it? Itâs very tempting to always default to a rewrite. If I write all the code, Iâll understand it. But who is to say the next person who looks at it will?
Similar to profiling code to identify the slowest spot, I work to identify the place that smells the most. Are there sections of the code that new devs are always struggling with? Are there frequent small changes that require touching lots of different files or methods?
Creating a list of smelly code helps identify which sections of code need the most attention.
Step 2: Pick the worst spot
Smelly code is like dirty dishes.
With a stack of dishes, Iâll plug my nose until I dispose of the rotting food thatâs causing the stink. It was easy to blame the whole pile, but for the most part, all of the other dishes are fairly clean. They donât need immediate attention. The rotting smell came from something I forgot to clean off when I was in a hurry.
When there is a piece of code thatâs really rotten, itâs often hidden somewhere in the pile. Maybe an abstraction went too far, spreading a hundred lines of code across dozens of files.
I keep in mind that I need to fix the worst smell; most of the other code is good enough and doesnât need my immediate attention.
Step 3: Resist the urge to do everything
Smelly code is never-ending.
Perhaps the hardest part of improving a code base is scoping it to one thing. Itâs so liberating to finally get a chance to clean up, that I can easily take it too far. Iâll think, âWhile Iâm at it, I might as well clean up this⌠oh! and that other thing needs fixing too.â
Resist! Do not do everything.
If I try to tackle everything, Iâm not going to finish. Even more likely, itâs not going to pass code review. Itâs better to do one piece at a time - ya know, like eating an elephant.
Step 4: Make sure itâs better
Smelly code has edge cases.
Inevitably, in the process of rewriting, I discover why the code was written that way in the first place. I might even stumble across a can of worms. At that point, I realize my not-so-dimwitted co-worker wasnât as dumb as I thought (or even more likely, I discover I was the one who wrote the code originally đ¤Śââď¸).
After learning all the edge cases, Iâll be tempted to walk away.
Step 5: Donât immediately give up
Smelly code is messy to work with.
Iâm frustrated imagining how far away the current code is from a better solution. Iâve got the code in my head, I know the edge cases, and Iâve got the context. Itâs important not to give up as the solution may be right around the corner.
I keep thinking about it while I go for a walk. Maybe even take a break. Solutions often come to me while Iâm on walks or in the shower.
Step 6: Use the co-worker bobblehead
Smelly code needs attention.
I steal my co-workerâs bobblehead and explain aloud what Iâm doing. In the process, I figure out what I've missed or overlooked.
If a bobble head isnât available, I resort to using my actual co-workers. (Iâm checking my assumptions by walking them through what Iâm thinking step by step.)
Step 7: Publish or throw in the towel
Smelly code can improve.
At the end of my steps I have a complete solution or Iâm banging my head on the keyboard. If itâs the first, I push the change and take a breath of fresh air. If itâs the second, I commit it to a branch and plan to revisit another day. Sometimes we canât have nice things.
Rinse and repeat
The depth I go into each step changes based on complexity or how critical the code is. Sometimes I can run through each of the steps in a few minutes, other times itâs spread out over a few weeks. It really depends on what Iâm working on.
Running through these steps helps me gradually improve my code. Thereâs nothing better than finally getting a fix for some smelly code merged and into production. Sometimes we can have nice things.
Dan Willoughby is the founder of Tellspin, an on-call scheduler in Slack for DevOps and developers (https://tellspin.app). Helping workspaces reduce their contact footprint, resolve incidents faster, and regain deep focus.
Starved for top-level software engineering content? Need some good tips on how to manage your team? This article is inspired by Dev Interrupted - the go-to podcast for engineering leaders.
Dev Interrupted features expert guests from around the world to explore strategy and day-to-day topics ranging from dev team metrics to accelerating delivery. With new guests every week from Google to small startups, the Dev Interrupted Podcast is a fresh look at the world of software engineering and engineering management.
Listen and subscribe on your streaming service of choice today.