7 Steps to Reduce Code Smell 🦨

#programming #codereview #tutorial #motivation

This article was contributed to devinterrupted by Dan Willoughby, founder of Tellspin

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.

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.