Spaghetti Deconstructed: Lessons from my first refactoring.

“What the hell was I thinking?” was my first thought when I revisited an old project from my last job. Reading and trying to re-establish my understanding of the logic was a daunting task to say the least. It really got me wondering what I could’ve done better in the past to make the process of refactoring easier, which inspired me to write this post. Here are 4 valuable lessons I learned from refactoring one of my oldest project.

MFW I look at my old code

Pasta: Descriptive variable names > Concise variable names

Naming variables always have been one of the hardest task for me. It’s not difficult to use a simple name for a value or function, but what is difficult is creating a name that convey its purpose. Also, I have a tendency to shorthand or initialize my variables, which seems like a great idea when I’m already familiar with the project. However, it’s a terrible thing to come back to when I’m revisiting an old code that is long forgotten.

Let me show you an example from my code:

#can you guess what they might mean?
axl=48.0
sproff = 12
ima1 = sproff
imb1 = axl - sproff
ima2= imb1
imb2 = ima1

hmmmm

Not terrible… but what do they mean? Let’s fix that.

axle = 48.0
spring_offset = 12
im_pos_a1 = spring_offset
im_pos_b1 = axle - spring_offset
im_pos_a2 = im_pos_b1
im_pos_b2 = im_pos_a1

Much better.
It’s still not too clear on what ‘im’, ‘a1’, or ‘b1’ might mean, but at least I can take a guess. The next step would be to add comments for clarity, which brings me to the next lesson I learned.

Sauce: Comment like you are explaining it to a 5 year old.

It’s been said thousands of times before and it will be said thousands of times in the future. Add comments to your code! Comment, comment, comment, you simply can’t comment enough! Well maybe not, but better to have a code that is inundated with comments than a bare code. Let’s build further on the previous example.

#-----------Geometric Constants, in inches-----------#
axle = 48.0 #axle length
spring_offset = 12 #spring offset from axle ends
#---------Intermediary Force Support Position---------#
#set 1
im_pos_a1 = spring_offset #support A location
im_pos_b1 = axle - spring_offset #Support B location
#set 2 - equal position as set 1
im_pos_a2, im_pos_b2 = im_pos_a1, im_pos_b1

So much better!
Commenting, in this example, established two very important things. First, it organized the code into visible subsections. Second, explained the purpose of each variable.

Let me show another example of commenting method that demonstrates another importance of commenting:

#this function updates the strings value dollar sign to numbers.
#Expected input: $425,112,413
#Output: 425112413 (as int)
def dollar_str_to_num(num_str: str):
    return int("".join(n for n in num_str if n.isnumeric()))

If you are an experienced coder, in this case Python, the function above should be fairly easy to understand. Some might even say the comments are unnecessary given how simple the code is and that the comments take up more space than the function! In reality, the lines spaces are cheap and you never know who will read or debug your code in the future. By providing a simple explanation of code logic, input, and output you’ll be saving a lot of time and headache in the future.

Don’t be cheap with your line counts!

Speaking of debugging, let’s move on to my third lesson. Debugging.

Meatballs: Keep your debugging statements.

Everyone probably had that at least one project that made you debug like this:

#some codes
print("It should be correct up to here")
#more codes
print("It runs up to here sometimes?")
#EVEN MORE codes
print("WHY")
#some more code
print("WON'T")
#maybe some bad variable assignments here
print("THIS F*CKING")
#buggy code
print("RUN")

Only to see that the buggy code exists in line 87, because of some stupid misspelled word. I’m exaggerating, of course, but as your project gets more complex, so does your error messages. Add the stress and fatigue of staring at the error messages for endless hours, sometimes you just might need to debug in more primitive ways like above. When you finally solve your bug, though, it’s a good idea to consolidate your debugging statements like below.

#Some code about function ABC
print("ABC takes x and returns IJK", ABC(x))

After you are done just comment them out rather than deleting them. You are essentially creating your own error messages for the future. Chances are if you are running into an issue in a particular section of the code, you will be facing similar issues in the future. Plus, if it’s been awhile since you revisited the code, it will help you remember the thought process behind your code much easier. Following that, the final lesson I learned:

Cheese on top: Revisit sooner and revisit often.

All my projects waiting to be refactored be like:

If you are like me you probably have stacks of code in the personal project list. Given how daunting refactoring is , or any overhaul projects, it’s not surprising that procrastination often gets the better of us. Remember that a lot of these don’t have to occur over night. Keep it simple and try to utilize some of the previous lessons I discussed. Start with print statements and relearn the logic of your code. As you start to remember the your past thought process add more comments to your code, leaving permanent reminders.

Whether you are a seasoned professional or a beginner, I hope that this was helpful. If you other tips or lessons from your refactoring please let me know in the comments below. You can also check out my git repository where I found the inspiration for this post.

you never know, you might have to code for 20 people some day