Maintainable Code vs. Common Code

Today, I’m going to answer a reader question that asks for my opinion on a blog post from medium.  In it, the other talks about what he calls “maintainable code,” but what I actually think of as “common code.”  Before I get started talking about these terms and the difference, however, consider the actual reader question.

I found this article and thought there was some interesting overlap with your 'Is Programming Art' article. What are your thoughts on this?

It  would probably help to read both pieces for background, but in case you don’t have the time, I’ll summarize the train of thought here.  In my post, the one to which the reader refers, I talk about the (small) intersection aesthetic appeal and software writing.  In the medium piece, the author, “Mr Galute,” draws a distinction between “brilliant code” and “maintainable code.”  Brilliant code, more or less, is the sort of code that requires a unique mind to dream up and a unique mind to understand, while maintainable code is the sort that any pro developer can maintain.  The overlap here is an interesting one, to be sure — this supposedly ‘brilliant’ code would seem to offer a specific kind aesthetic appeal in the same vein as solving a math problem in an unprecedented, but needlessly complex way.

As for what I think of the post itself, I’m skeptical as to the existence of this ‘brilliant’ code, and I suspect the author is a bit too.  He makes a point that I really like in the first part of the post, and then, unfortunately, in my estimation, follows it up with something of a non sequitur in the form of examples of what he considers to be “maintainable.”  Here’s my quick summary of his post, if you don’t want to read it in its entirety.

I worked with a guy that was (or seemed) really smart.  He wrote crazy complex code and acquitted himself well in justifying it, so we assumed it was necessary.  This brilliant coder was also something of a bully, intimidating and chasing off anyone who dared question his special, unique approach.

But then he left, and we’re kind of screwed.  Nobody really understands what he did, which means that we either need to maintain code that we don’t get or else that we need to rewrite it.  Management learned its lesson from this, and realized that it’s better to have boring code that the group understands, rather than ingenious code that only one person understands.

I am absolutely with “Mr. Galute” up to this point, and I would probably even take a stronger position.  I’d argue that his difficult but ‘brilliant’ former colleague wasn’t actually particularly brilliant.  It takes a lot of cleverness to write code that both contains complex, unique approaches and that your colleagues can understand.  It doesn’t take as much cleverness simply to write code that no one understands and then to bluster a lot about it.  That’s the stuff of which expert beginners are made.

But then Mr. Galute goes on to explain what it means to write maintainable code.  This is something he calls “the 10 commandments of maintainable code in C” (though he argues that they are applicable to C# as well), and they round out the post.

1. Thou shalt comment thy code.
2. Thou shalt use white space.
3. Thou shalt use meaningful variable names.
4. Thou shalt use indentation.
5. Thou shalt not squeeze all thy expressions into one line.
6. Thou shalt include all the headers thy code needs.
7. Thou shalt be explicit in they requests of the compiler.
8. Thou shalt use methods and functions to break up thy code.
9. Thou shalt use braces for thy loops and conditionals.
10. Thou shalt use parentheses to control operator precedence.

After being completely with him up to this point, I found myself scratching my head as I read these.  Maintainability is the property of code that lets maintenance programmers make changes relatively quickly and with low risk.  Is that really what’s being described here?

If you’re a regular reader on this blog, you can probably imagine what would be first and foremost on my list of things that make code maintainable: automated unit tests.  If a method is well covered by unit tests, maintenance becomes a breeze — you know immediately if you’re breaking anything, so you can get in there and do what you need to with confidence.

Other properties of maintainable code include avoidance of excessive coupling, minimization of global/shared state, favoring immutability, minimizing path complexity, conforming to the Open/Closed Principle, and generally abiding by the Principle of Least Astonishment, to prevent your code from containing mental landmines.  Thus I would imagine commandments of maintainable code to address things that affect how you reason about code.  These ‘commandments’ mostly don’t.

In fact, 6 of them are entirely superficial: (1), (2), (4), (5), (9), and (10).  I say this because those are all properties of the code that can be auto-fixed easily by an IDE plugin.  That is, with things like “use indentation,” you can literally have your IDE fix that for you every time you save a file.  So, how serious a barrier to maintainability can these things possibly be?  If you don’t like the way a piece of code looks vis a vis these items, it costs you only the fraction of a second required to hit a keyboard shortcut — hardly a maintainability deal-breaker.

And yet, the things he’s talking about do matter to people.  They’re typically the source of a lot of squabbling among teams trying to normalize on a coding standard, and they can be frustrating when you’re trying to read code.  But they’re frustrating not because they’re wrong or because they intrinsically cause maintenance difficulty — they’re frustrating because they’re not what you’re used to.

It is for this reason that I propose the term “common code.”  Maintainable code is code that can be modified cheaply, quickly, and with low risk.  Common code is code that conforms to the group’s standards or, absent that, to common industry practice.  Writing maintainable code is an important competitive advantage, from a business perspective.  Writing common code is common courtesy to your teammates.

I would advocate that people write both maintainable code and common code.  But I’d caution against confusing the two.

If you have a question you’d like to hear my opinion on, please feel free to submit.