It’s Better to be Clear Than Clever

In my years of coding I have had the opportunity to work with, or after, a wide range of types of programmers. Both self taught and professionally trained, and in small and fast paced companies there wasn’t always a set of coding standards in place leaving developers to do what was best in their opinion. Being exposed to such a wide range of approaches proved to be a good way of reading into how each developer thought. It certainly had its entertaining moments. Without a doubt, the biggest lesson extracted from all of this is to leave your ego out of your code, to go the extra mile and to be clear on not just what you are doing in a piece of code, but why. Context is king in code as well!


I’ve often read on the twitter-sphere macho-developer statements like “If it was hard for me to code it, then it should be hard for you to read it”. This couldn’t be further from the truth and is absurd in any context. No developer worth their salt will look at complicated, poorly documented code and think the author was a genius. “Boy That Guy Must Have Been A Genius” often means “That Guy was an Idiot”. One of the finest examples I’ve seen of this was a function which I inherited which was in excess of five pages of undocumented code with a 3 line expression built into the return statement with the comment “Voila!”.


Patterns Exist for a Reason

Documented software patterns exist because they work and can be easily understood. In this day and age, it is extremely rare in a line of business application that you are coding, to come across a type of problem that someone hasn’t already been tackled. As much as we engineers have a burning desire to disassemble the wheel and rebuild it better for our particular case, you should keep these urges to yourself and your side projects. You have to remember that your code will live on, be reused for new use cases, and supported by people other than yourself. You need to be clear and concise.


When it’s Right to Break the Mold

There are some cases when you have to get creative, and color outside the lines, and write unique algorithms to solve a problem. These cases happen less often than most developers want to believe and are largely limited to cases when there are serious performance concerns, when working with odd third-party libraries, or some odd requirement specific to your domain. While even these problems are most likely solvable via standard approaches, if you do have to right complex, out of the box code, try to abstract away the complexities such that they do not appear to consumers of your code, and do not clutter otherwise straight forward code. And for Bob’s sake comment your code!


Comment the Reason you are Doing Something and the Problem you are Solving

At the top, before any logic, be clear to discuss what you are doing and most importantly, why you are coding things the way you are in complete sentences. Its good for the company, good for the life of the code, and good for the next developer that has to trace through or enhance the code. Do it at least for selfish reason so the guy or girl down the line doesn’t call you a dope for writing convoluted, undocumented code. I’ve seen countless cases where developers simply leave their name and a timestamp only to have the next developer come through on a bug hunt and say “that looks weird” and change out the purpose done logic. Leaving a comment of your name/initials and a timestamp is as useful as carving it into the walls of the bathroom stall.


This post started off as a rant after a string of projects of porting legacy code into C# several months ago. I decided to come back to the topic and finish this post in hopes that you share it out, and just maybe someone who was about to comment their code with “// Joe 09/18”, will go back and put some more thought behind it before committing the check-in. It all boils down to, if you are going to do something, do it right.


Leave a Reply