Not too long ago, while browsing through Slashdot, I saw an interesting request for advice from a programmer: How do you tell someone he writes terrible code?
“I have a coworker who, despite being very smart and even very knowledgeable about software, writes the most horrible code imaginable. Entire programs are stuffed into single functions, artificially stretched thanks to relentless repetition; variable and class names so uninformative as to make grown men weep; basic language features ignored, when they could make everything shorter and more readable; and OOP abuse so sick and twisted that it may be considered a war crime.”
Coding style is as personal as a fingerprint. Programmers all believe that their way is the best. “It works, doesn’t it?” can stop most complaints. And, “I don’t have the time to rewrite it, you do it,” will likely stop the rest.
But this is a continuing conversation, one that has been going on probably since Bletchley. Over the years, many good and thoughtful people have attempted to codify good coding practices—where to indent, how far, how to structure an if-then statement, and so on. But sometimes it seems as if programmers, as soon as they get a little confidence in what they’re doing, also invents their own coding styles. Some are efficient. Others, not so much.
In the glory days of newspaper and magazine publishing, writers had style guides telling them where capital letters are necessary, when punctuation goes inside the quotation marks and when outside, when to use italics, when to spell out numbers and when to use actual digits, where to place the hyphen, and so on. Even today, the most important resource book on any writer’s shelf is Strunk and White’s “Elements of Style,” also known as “the little book.”
There is no such definitive style guide for programmers, possibly because there may be no right way to write code. Programming is a craft requiring high skill; occasionally it is even an art. And at the very bleeding edge, there may even be a bit of science involved, because when you construct a new algorithm, you might also be expanding the domain of human thought.
Good code works. It does the job and it does it in an acceptable amount of time.
Back in the days when every clock cycle counted, some foundries developed tools to analyze where the program was spending most of its time. Often, they discovered that 10% of the code was doing 90% of the work. So they’d go into those loops and replace key lines of code with calls to assembly language routines. You don’t need to write your menu function in assembler, but a loop that will go through thousands of iterations will benefit enormously.
But there’s another aspect to good code. It has to be understandable. A year from now, you might have to return to this code to patch a bug or add a feature or adapt it to a change in the operating system. If you have to spend a large amount of your time just puzzling out what you did in the first place, it’s not good code. And if you’re coming to someone else’s code… well, murders have been committed for less.
Good code isn’t just well structured, it’s well commented. Yes, I know, writing comments is tedious. You already know what this function does. You’re impatient to get on to the next part of the job.
But one of the programmers who mentored me through BASIC and Pascal and a little bit of assembler was adamant about commenting. At the time, I felt he was being overly fussy. I thought that once code was written, it was finished. But a year later, returning to a small utility I’d dashed off for myself, I understood exactly why he’d been so severe on this point.
Eventually, I developed my own commenting style:
Procedure WarpSpeed (InputNum: Real);
{This procedure receives a value between 0 and 10, changes starship warp speed to that value.}
If
InputNum >= 0 and InputNum <=10 {Validate input}
Then
WarpSpeed := InputNum {change warp speed}
Else
ScottyReport (“Cap’n, that makes no sense!”) {reject input}
End;
Coming back to this a year later, it would be an easy matter to fix this code to allow for trans-warp speeds of 11 or greater. But as I developed this commenting discipline, I discovered that it was also changing the way I approached code. I found that it was sometimes easier to write the comments first, because it would give me a clear overview of the entire algorithm.
{Get power request}
{How many Dilithium crystals?}
{Enough to meet power request?}
{How much stress on crystals?}
{If stress is greater than allowable, report stress then}
{If enough crystals, meet power request}
{Else Scotty says he cannot}
Working from that, writing the necessary code will be a lot easier. Today, my personal philosophy is that code without comments is incomplete. Worse, it’s often impossible to decode in a reasonable amount of time.
Speaking to the incident that started this column, what leapt out at me was this phrase: “variable and class names so uninformative as to make grown men weep.” Well-commented code tells you what’s going on inside the algorithm, but more than that, it gives you a clearer sense of what the programmer intended to accomplish throughout. It gives you an overview, a larger insight into the thinking behind the algorithm. The programmer above, unhappy with his coworker’s code, obviously has a bigger problem than just the lack of commenting, but the lack of documentation has seriously exacerbated the problem.
Different programmers, different code foundries, different companies all have their own styles. Some even have their own style guides, but many more do not. Sloppy coding practices could be just as inefficient as sloppy code.
What do you think?
David Gerrold is the author of over 50 books, several hundred articles and columns, and over a dozen television episodes, including the famous “Star Trek” episode, “The Trouble with Tribbles.” He is also an authority on computer software and programming, and takes a broad view of the evolution of advanced technologies. Readers may remember Gerrold from the Computer Language Magazine forum on CompuServe, where he was a frequent and prolific contributor in the 1990s.
