Writing Good Code

I just read an article in IEEE's Software November issue about writing good code, and it resonated so much with me that I couldn't pass up the opportunity to share my thoughts about it.

The article, which unfortunately I cannot link (since you need to have a paid subscription to read) explained what makes bad code, how we deal with bad code, and what we can do to stop ourselves from writing bad code. Before I dive deeper into my thoughts on the article, I wanted to write a little bit about my past with writing code and why "bad code" is something that I think about quite often.

I think that I am a great example of someone who writes bad code. Not necessarily all of the time, or even often for that matter, but I have written my fair share of terrible code (as has probably every developer ever - unless you are superman). The problem with me though, is I find myself not intrinsically motivated to write good code often. For example, in one of the classes I had to take last year, we were graded on the "style" that each of our coding projects had. This meant we had to functionally decompose often and with purpose, we had to indent correctly, and comment wherever possible. This motivated me to actually make sense of my code and even attempt to map out the programs that I was creating on paper before typing anything out. I was finally attempting to write "good code." But then my teacher gave us a project where style wasn't a part of our grade. I believe my entire project was written in my main function, and it totaled about 700 lines. If I had been graded on style, I would have received a big fat "F". So why was it that I needed this external motivation of a grade in order to write good code, something that every software engineer is supposed to have inherently etched into their brains? What was it that was making me so discouraged from making my code more efficient, and why after coding for two years was I still not getting it?

That's where this article comes into play. First, how do we even measure good code? What is it about code that makes it more optimized, or easier to debug, and which of these things is more important when I am writing my code anyways? The article highlighted a very good point in that there are many bad ways of writing good code. In the past, some project managers would tell their developers that their productivity could be measured by the number of lines of code you output over the units of time spent on the code. Or the quality of the code could be measured by how many lines of comments you had in comparison to how many lines of raw code you had. Both of these are ultimately ineffective when thinking about "good" code because:

1. If you are solely trying to write more lines of code for every hour you are coding, then you could write a million lines of garbage in an hour and be considered a better developer than someone who wrote one amazing optimal line in the same amount of time.
2. Comments aren't technically always going to be something that helps your code be considered "good." Yes, it definitely helps in the debugging and code review process so that people can understand your code more easily (which is VERY important). But, unfortunately you could be the best commenter in the world, and still write the worst code anyone has ever seen.

This is also explained in Goodhart's law where he states that "When a measure becomes a target, it ceases to be a good measure." So how in the world are we supposed to write good code? And how can I hold myself accountable when I don't even know what it is that will make my code "good"??

As I frustratingly read this article, I was thinking that my questions would go unanswered forever. Until I read the last little blurb - "Dreaming in Code." It explains an algorithm for creating a postfix to prefix converter and how one person was able to create such an optimal way to do so. Everyone wondered how someone was able to so succinctly write this converter without drawing on any other code and implement it in literally the best way possible. How was he able to do this? It was simple: he understood how to convert from postfix to prefix at an incredible level. This was a highly mathematical problem that he had mapped out in every way in order to find the most optimized solution. So, what they are saying is basically the only way to write truly good code is to fully understand what you are writing. Seems a little self-explanatory doesn't it? It's surprising how many developers actually don't think about this though.

To highlight a little bit on this: in one of my computer science classes (say with 30 people in it) for any given assignment, if the teacher gave us an explanation for a program and gave us exactly one hour to write and implement it I almost always see the following happen:

• 25 out of the 30 people will instantly pull out their computers and start typing their algorithms or programs right away.
• 2 or 3 people will sit and think for about two to three minutes and then start typing their solutions.
• One or (maybe) two people will pull out a pencil and paper and map out their ideas for 15 to 20 minutes before even starting to write one line of code.

So who is the better programmer? And whose code is going to be "better"? Obviously this is all subjective and there is no real way to measure this (since it depends on the people writing the code and the students within the class, etc.). But, I can almost guarantee that the people who mapped out their solutions beforehand are going to have better code than a majority of the rest of the class. Why is this you ask? Because they understood the problem. They were able to map out possible solutions not only in their brain, but through simple testing on paper before even considering writing a single line of code. They already knew what special cases to test for and to account for in their code. They started typing without any questions left in their brain about how to implement a certain function. They utilized their time better, created a more optimal solution, and wrote good code.

That is my takeaway from all of this. I may not have found an incredible external motivator to write extremely optimized code, and I may not even have the capability of writing such code yet. But as long as I focus my efforts on fully understanding my coding projects before I dive headfirst into them, hopefully I (and every other developer out there) can learn to write better code. And with practice and experience, eventually I may be able to be someone who can write good code. Until then, I'm going to get out my paper and pencils.

Thanks for reading, and I'll catch you next time.