3 Coding Follies Your Future Self Will Wish You Avoided
Spare yourself the headache, and that inevitable moment when you question your career choice
Writing code is much like writing anything else; organization is critical. When you are working with previously written code, attempting to increase functionality or fix a lingering issue, it will take some time to get familiar with what the code does and how it works. This is a given, but you can limit the amount of head-scratching you will do later when you try to figure out what your past self was thinking.
There are three follies that you should avoid:
- Reduce obfuscation — keep things easy to take apart and locate, do not over-engineer
- Use useful variable and function names
- Do not cut corners
It seems like a simple list to follow, but you can easily paint yourself in a corner if you are not careful.
Obfuscation
As developers, we want to streamline our code using object-orientated programming. We can model real-life objects and situations because, more than likely, a program is being written to solve some real-world problems. Let’s say we want to write a program that is going to assist a land surveyor. We want our program to take the lot and calculate the area and the perimeter of the property.
We quickly identify that the lot is nothing more than a shape, so we start down that path. We write a simple interface that will get us going in the right direction. You never know we might want to know how many sides the lot has, could be useful.
Lots can have many shapes with many sides, so it makes sense to create an abstract class.
Lots can be rectangular shaped, so let’s add a concrete polygon.
Lots can be circular or square too, why not?
We have a good thing going here, a polygon can hold any shape you throw at it, and for good measure, we can support circles too. We pat ourselves on the back on the excellent legwork upfront to make this problem an easy one to enhance and maintain.
We give it a test ride and throw some shapes at it.
Oh no, it blows up! Well, I thought we might have circular lots, but in reality, we probably will not, so let’s take that out and give it another go.
Gee, no area. That seems strange. To figure out where things went wrong, we have to untangle a mess.
It seemed like a good idea to return an object for the area calculation and perimeter calculation. Still, we introduced a problem; all of our shapes are not producing the same object. We can force the calculations to return another interface that allows for flexibility and reliance. Once again, are we being clear; what we are trying to do? Will this be easy to take apart if we need to, or are we over-engineering the problem? The simple answer is that it is not clear; we have obfuscated this one up real good.
This is my function — I love it, and I will call it Bob
I love it, and I will call it Bob. Naming things is hard. We try to come up with suitable names that make sense and are consistent with what the function is going to do, or what the variable will represent. We want our functions when called to sound valuable — something like:
My name is Maximus Decimus Merridius, a function of an inherited class, and in this lifetime or the next, I will escape this stack frame.
But most times, we end up with my name is Gladiator.
In my experience, you will get burned when you have two functions that are similarly named. Your IDE (Integrated Development Environment) will more than likely have Intellisense and will be a good pal and try to help you pick the right function.
Something like:
You could easily pick the wrong one. In my case, I was calling a function that was not making use of a schema-bound view with indexes and had the potential to be much slower. You won’t notice anything immediately, but you have to be aware of what you are naming things and make them distinct enough, so you pick the right one.
Don’t Cut Corners
Refactoring is inevitable; you will never get it right the first time. Things change, and scope changes. I was working on a project that would allow for a business expert review submissions to a set of data that managed inventory out in the field. The initial catalog of inventory comprised several fields that made up the model. To approve, decline, or place the suggested changes into a pending state, the inventory model needed to be de-normalized and placed into a single row. I mapped each field of the inventory to a column in a table. There was another table that maintained the state for each field.
The original model was modified slightly, and in the de-normalized table, we had some fields that we no longer being collected. The scope of the inventory expanded, and new fields needed to be added. The changes had to be queued to the data management team if anyone modified the database, which became a hurdle.
What about using the fields that aren’t being used anymore? We can repurpose those. You can do this, and document the repurpose if it fits. However, imagine it is someone other than yourself working on the project next. Chances are the next person working on the project will not know that field “DockLength” really is the number of parking spaces.
So don’t cut corners, do it right and make it clear. Use appropriate names and always think about the next guy. It could be you in the future wanting to strangle your past-self and muttering under your breath how you should have been a dentist.
