Some years ago when I was writing in C, I came across the 10 Commandments For C Programmers written by Henry Spencer. It is still all over the internet. The ensuing conversation led myself and some colleagues to come up with the 10 Commandments of Maintainable C, a document I recently found a copy of and have shared below. Reading through it, I found it still surprisingly applicable to my current world of C#. It also started me thinking again about how to write maintainable code.
The Organisation I work for have had a project running for the last 18 months or so and have recently not renewed the contract for one of the contract developers that was employed on that project. As a consequence of this, I was moved on to this project.
This contractor was quite brilliant, a coding rock star, everyone was in awe of his skill with the keyboard, and often went and sought his advice for the more esoteric coding problems.
That was the problem, no one on the project felt confident enough to challenge him on his work enough for him to back down. He regularly threw temper tantrums but because he was perceived as being someone the management thought we needed, he was pandered to. One developer I know challenged him about the complexity of what he was writing, his response was “why shouldn’t I do the best I can, why should I dumb it down”. The developer wasn’t confident enough to follow it through and the contractor won the argument and continued as before.
Now he has left and no one likes going into his code because it is so difficult to understand. I don’t actually know the full story of why he left but I do know his attitude played a part in it.
The management realise now that he had been a loose cannon and that his work had not been given enough oversight, a mistake we will not be repeating. Unfortunately we were out of time and most of his work had to go live, now we have to support it or re-write it, neither choice is particularly appealing.
There is no problem writing brilliant code if the brilliant coder is the only one who is ever likely to work on that code in the future. Unfortunately that is rarely the case in a commercial organisation.
The peak of achievement for any developer is elegance. Having you code declared as elegant is the ultimate accolade. Elegance encompasses understandability, efficiency, simplicity and a hundred and one other attributes that denote best practice. But ultimately it is the other developers saying, “I’d be happy to work on that code”. That is the epitome of maintainability; writing code that another developer, with little or no context or head scratching, can begin working with. Whilst elegant code requires skill and often a certain amount of luck, maintainability is not that difficult to do but because it rarely receives accolade, which incidentally is in itself an accolade, too many developers don’t do it because they want their code noticed. It is so easy not to notice maintainable code in the same way no one notices an efficient shop assistant.
So which one benefits the organisation more, maintainable code or brilliant code? As far as I’m concerned there is no contest but still, for so many managers the allure and kudos of employing a ‘Rock Star’ is still very compelling.
So, finally, those 10 commandments, feel free to criticise, copy and amend. Since first publishing this article, it has been pointed out to me that these ‘commandments’ are out of date, a few clicks in a modern IDE and it will do it all for you, that you don’t have to worry about it anymore. Yes, that’s a good point, just as long as those ‘few clicks’ are done.
1. Thou shalt comment thy code
Use comments wisely to proclaim thy reasons. Do not procrastinate for thy audience shall grow weary of thy ramblings and miss the moral of your tale. Do not repeat thy code as a comment for thy audience shall wonder what ails you and ignore your efforts as the work of a fool. Thence when they miss a proclamation of great wisdom, they shalt curse you all the more.
2. Thou shalt use white space
Use white space wisely to make thy code pleasing to the eye. Thy compiler cares not if white space dances amongst your code and it will author the same object code be it there or not.
3. Thou shalt use meaningful variable names
Christen thy variables so that thy audience shall know their purpose. Thy compiler will accept the first 32 characters of thy given names. Use them wisely to enhance thy tale and thou shalt be proclaimed a great writer of code by thy audience.
4. Thou shalt use indentation
Indentation breathes order and clarity on all it touches. If thy code is to be read by future generations, then thou must indent. Beware of using indentation that doth change with the wind for that same wind shall dispel any meaningful proclamations of order and structure spoken by the code.
5. Thou shalt not squeeze all thy expressions into one line
Thy compiler may happily understand many concatenations of statements but thy audience will not. Thy proclaimed brilliance at the scribing of code is not proportional to thy level of concatenation. Should you follow the gospel of maximum code in minimal lines, the heart of thy fellow scribes shall sink when the history fortells thy name as the author.
6. Thou shalt include all the headers thy code needs
Thy compiler is blind to external symbols less you include the headers that proclaim their meaning. Include them and it shall guide you through the labyrinth of declarations and definitions. Beware of relying on header files to include other header files for you. Those header files shall be changed by other scribes who know not of the reliance your code has on them.
7. Thou shalt be explicit in thy requests of the compiler
Never depend on the compiler to guess your unwritten intentions for its work. Although it is predictable is its authoring of object code at the time of your scribing, the great gods that write our compilers may change their minds. Woe and misery shall befall the poor unfortunate that has to sort out the code that suddenly doth not work.
8. Thou shalt use methods and functions to break up thy code
Never ending sentences doth leave the reader out of breath. Never ending code doth leave the maintainer with a tangle of string. Threading the new string in without moving the old is like a blind man playing Jenga.
9. Thou shalt use braces for thy loops and conditionals
If thy condition has no brace, but one line the compiler shall take for execution. Should this line be a macro with many lines, then only one line of the macro shall the compiler take. Woe betide the poor unfortunate trying to sort that one out.
10. Thou shalt use parenthesis to control operator precedence
Pride comes before the fall, and fall ye shall if you think your knowledge of precedence is all powerful. Use parenthesis to proclaim thy intentions for all to see, including the compiler.