Coding Standards and Orthography

Sometimes when I bring up the subject of coding standards, I get an eye-rolling, aren’t-we-all-adults-here kind of reaction from my fellow programmers — or a fearful look anticipating endless debates about where the braces should go. Of course, “coding standards” can cover a gamut of subjects — from techniques to avoid shooting yourself in the foot to parenthesis placement — but even the little stuff matters, because writing code is largely about communicating with humans.

The adage says, “code is read more than it is written.” If this isn’t completely obvious, try this experiment:

  1. Turn off your monitor
  2. Write some code
It’s pretty hard to write code without at least reading it once, so if you ever read it again you’ve satisfied the adage’s assertion. Chances are that you or someone else will read the code many more times.
Flippancy aside, a survey of software maintenance cost studies shows that greater than 90% of the cost of software is in maintaining and enhancing it, and “Studies of software maintainers have shown that approximately 50% of their time is spent in the process of understanding the code that they are to maintain.”
If you accept the premise that code is a form of written communication with people as a primary audience, then it makes sense to draw from the ideas of similar systems with hundreds of years of experience behind them, like say, written English.

Orthography (literally “correct writing”) are the rules of writing a language, with special emphasis on standardized spelling. There was an argument and rebuttal a little while back in Wired Magazine for doing away with standardized spelling, which was also covered on NPR.

In the NPR interview, Anne Trubek says:

So my basic argument is that if you look at the history of the English language, a lot of people think there are sort of immutable laws that are, you know, God-given or laws of nature. But actually, it’s a bunch of manmade prescriptions and guidelines that change over time.

In other words, Trubek is saying that correctness is somewhat arbitrary, but as something becomes standardized, people start to treat right and wrong in an almost moral sense that isn’t justifiable.

Lee Simmons, a copy editor for Wired, who has the job of making sure words are spelled correctly, responds with:

I would say spelling rules, for what they are, they’re all about making communication easier. If I could use an analogy, the Internet itself is essentially a set of standards – hardware and software standards – that make it possible for people with different devices to communicate. It creates a universal platform. And I would argue that our English spelling system, for all its flaws, provides just such a universal platform…. We can argue about whether we ought to reform the standards, make the system more logical, but I would argue that the standards themselves are something that we need to preserve.

Simply put, it’s easier to read words that are spelled how we expect.

English also developed standard punctuation and good style, again with the objective of writing to be understood, but we sometimes forget things like that when writing code. We laugh at “The Department of Redundancy Department”, but many programmers don’t see anything wrong with code like:

// find the customer with the id
var customer = Customers.Find(customerId);

or

return (a == b) ? true : false;

Does it matter where braces and parentheses go? Certainly not in any moral sense, but there are standards that are more logical than others. If you’re reading an English sentence with parentheses (like this one) and suddenly things get a little weird( like this )then it interrupts the communication. Or what (if I) just start) throwing unnecessary( parentheses in?

return (theResult);

Communication is actually kind of hard. Consider the fact that professional writers, who presumably have some talent for communication, almost never publish the first thing that shows up in the word processor. They revise, rework, rewrite until their ideas are expressed well. Then someone else comes along to fix the places where the writer still didn’t get it quite right.

Do people even notice if you make a similar effort to make your code easy to read? Or do they just say, “Oh, that’s easy,” compared to looking at some complicated mess and say, “Wow, that guy’s smart”?

Coding standards are a tool, one of many available to programmers to facilitate communication. Why not take advantage of it? Your future self will thank you.

4 thoughts on “Coding Standards and Orthography

  1. Hi Jeremy — thanks for the comment.

    Maybe the converse to Joel would be don’t make right code look wrong. Many languages these days have some level of coding standards ready-made, so you’ll read a lot of code that follows them. If you run across some code that rampantly violates them, I think it impedes your ability to read the code. Evn thow yu kan reed these im pritteeshur its distrakteeng todoso.

    I also wonder if what Joel really wants is more specific types — something I know I’ve heard you talk about before. If string and unsafe string shouldn’t be assignable, make them different types and let the compiler catch your mistakes instead of your eyeballs. But that isn’t necessarily always practical, in which case naming standards seem helpful in making the code more comprehensible and correct — so long as people understand and follow the standards.

    With respect to English, I don’t think I quite qualify as a snoot :). I know what dysphemism means, but I don’t usually flaunt it because there’s too much of English vocabulary and usage of which I’m ignorant. When I hear someone say, “It causes less bugs,” my brain auto-corrects to “fewer bugs”, but I try to keep quiet about it because it usually doesn’t matter.

    My wife writes for the local newspaper, and she frequently asks me to be her first-level editor before submitting a story. At that point, I do try to catch everything I’m capable of, since in that professional writing context, it does matter.

    Thanks again.

  2. The point I was trying to convey with the DFW article wasn’t really around being a syntax snob. I was aiming more for “style and usage are really complicated; even more complicated is making a ‘guide’ to style and usage because people tend to disagree about these things quite passionately.”

    For example, taking your ternary operator example,

    return (y > x) ? true : false;

    …frankly, the parenthesis do not bother me in the slightest. I think it may be more clear to read, particularly if the conditional statement isn’t obvious. Sometimes the additional parenthesis in an arithmetic or logical statement are superfluous, but can help clarify intended order of operations. Sometimes not having parenthesis just makes it a brain-twister, and operator precedence rules aren’t necessarily the same between languages.

    You and I had an exchange about “yoda” statements:

    if( true == dayTime ) { … }

    I personally find this irritating. I’m not alone either, because it reads strangely when you think about it in terms of the English language, and I generally tend to structure my code so it reads like English. It’s sort of like saying “if blue is the sky” or “if friday is today” or the ever-classic “try you must.” You fairly countered with the point that it skirts a class of bugs resembling:

    if( true = someVariable) { … }

    ….since a compiler would catch that “true” is not a variable, and thus cannot be assigned. That’s a valid counterpoint, particularly since this sort of assignment inside a conditional isn’t uncommon in languages like C. It doesn’t change the fact that “yoda” speak drives me nuts, or that either is “technically” correct and it’s a style difference, or every time I see a piece of code written in “yoda” speak I am sorely tempted to swap everything.

    I’ve never derived value from a “coding standard” debate. That’s not to say it is valueless; I accept that I May Be Doing It Wrong and am a pedantic jerk who’s doing the whole “eye-rolling, aren’t-we-all-adults-here” thing. But most of the problems I see in code tend to be more “structural” or “architectural”: superflous threads, APIs that are overly complicated, OO where it shouldn’t be used, no OO where it should be used, algorithms that are more complicated than they should be, premature optimization, public APIs with “just in case!” bells and whistles, etc. In my experience stuff most “coding standards” documents deal with are mere annoyances that aren’t in the same league as tightly coupled classes and pointless dependencies, threading for no reason other than a total lack of foresight, places that should track state clearly that instead rely on some motley collection of booleans, 200+ line functions with nested loops and five or six levels of depth, massive piles of “just in case!” code, and so forth. And fixing issues like these isn’t a matter of having a “coding standard.”

    Tool in the arsenal? I suppose so. But in my experience, not a particularly effective one. Maybe someday someone will show me otherwise.

  3. I think we actually agree on a lot of things here, despite your aversion to “coding standards”. An example of a pragmatic style guide is Python’s PEP 8 (http://www.python.org/dev/peps/pep-0008/). It’s there (no serious debate required), IDEs can help you conform to it, and its stated reason for existing is that “Readability counts”. I try to follow it.

    I did fail to communicate my example well. I don’t have a problem with the parentheses in ternary operator example. I have a problem with there being a ternary operator at all in this case. The line takes a boolean expression and uses the ternary operator to convert it into another boolean expression. This is enough:

    return (a == b);

    I totally agree with your “yoda” point. When I was a C programmer, we had a coding standard to break readability because of the assignment bug mentioned. So while I understand why people got into that habit, I cheerfully ditched it long ago when I started using languages that warned regardless of the order of the operands.

    To be sure, there’s all kinds of ways code can be bad — as your list shows. No amount of perfect spelling and punctuation will save a story with a horrible plot, but eventually those should be there in a finished product.

Leave a Reply

Your email address will not be published. Required fields are marked *