7 Steps to Reduce Code Smell

Code smell is a way to describe code that hasnt 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 Im not careful, Ill 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.

Im 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 dont have time for this, Ill say to myself.

By the 5th or 6th hour Ive 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? Its very tempting to always default to a rewrite. If I write all the code, Ill 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, Ill plug my nose until I dispose of the rotting food thats 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 dont 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 thats really rotten, its 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 doesnt 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. Its so liberating to finally get a chance to clean up, that I can easily take it too far. Ill think, While Im 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, Im not going to finish. Even more likely, its not going to pass code review. Its better to do one piece at a time - ya know, like eating an elephant.

Step 4: Make sure its 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 wasnt 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, Ill be tempted to walk away.

Step 5: Dont immediately give up

Smelly code is messy to work with.

Im frustrated imagining how far away the current code is from a better solution. Ive got the code in my head, I know the edge cases, and Ive got the context. Its 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 Im on walks or in the shower.

Step 6: Use the co-worker bobblehead

Smelly code needs attention.

I steal my co-workers bobblehead and explain aloud what Im doing. In the process, I figure out what I've missed or overlooked.

If a bobble head isnt available, I resort to using my actual co-workers. (Im checking my assumptions by walking them through what Im 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 Im banging my head on the keyboard. If its the first, I push the change and take a breath of fresh air. If its the second, I commit it to a branch and plan to revisit another day. Sometimes we cant 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 its spread out over a few weeks. It really depends on what Im working on.

Running through these steps helps me gradually improve my code. Theres nothing better than finally getting a fix for some smelly code merged and into production. Sometimes we can have nice things.

This article was written exclusively for devinterrupted by Dan Willoughby, 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.