Talk About Quality

Tom Harris

Very Short Coding Standard

with 4 comments

I’ve read any number of coding standards. They’re usually long, hard to imagine any developer memorizing them, and not automatically testable. So I was pleased to see Gerard Holzmann’s attempt at something much shorter, in the June 2006 issue of Computer Magazine: The Power of 10: Rules for Developing Safety-Critical Code.

Holzmann is the lead technologist at JPL’s Laboratory for Reliable Software, so his proposal is definitely worth reading.

But coding standards always bring up arguments about what should or shouldn’t be included, as well as doubts about how, or how costly, to implement.

There’s even a question of whether, in a project that has neither code reviews nor static analysis, which to start first.

In that spirit, then, I offer this Very Short Coding Standard (VSCS) as a possible starting point for projects that need to “do something”. Just two items: one from the human side of things — requires code review to verify, and one based on a static analysis tool that everyone already has installed.

VSCS Rule #1: Use Meaningful Entity Names

VSCS Rule #2: Maintain Zero Compiler Warnings

My experience tells me that you get a big improvement in readability if you can come up with entity names that are obvious to reviewers as well as to yourself. For the power of compiler warnings, read Holzmann’s Rule 10

Failure to meet either should break the build and be handled immediately by refactoring.

VSCS is short, but not as easy to deploy as it might seem.

If your organization thinks it should do much more, first get this working and then go further.

Written by Tom Harris

July 9, 2006 at 2:15 pm

Posted in Code Quality

Tagged with

4 Responses

Subscribe to comments with RSS.

  1. Holzmann states, “Static analyzers have a somewhat bad reputation due to early versions that produced mostly invalid messages, but this is no longer the case. The best static analyzers today are fast, and they produce accurate messages. Their use should not be negotiable on any serious software project.”

    Is there a static analysis tool that you recommend?

    J A Miller

    August 22, 2006 at 8:04 am

  2. Short answer? Your compiler.

    Turn your compiler warnings all the way up and run your make file with the warnings parsed and linked to jump to the offending line of code. Get used to reading, understanding, and fixing them. In rare cases, you can turn off a single warning for a single line of code, and comment it with a good explanation why the compiler writer didn’t foresee your essential need for the construct that produced a warning.

    Longer answer:

    After your code is continously compiler-warning-free, move on to static analysis tools. There are so many out there — many of them free. I’ve used Splint (www.splint.org) for C. I see that there’s Findbugs for java with a plug-in for Eclipse. Microsoft compilers come with static analyzers built in as well — you just have to turn them on and use them.

    The key is to have an ongoing “discussion” with the (author of the) compiler and additional static analyzer. You wrote some code to finish your detailed design. The (author of the) analyzer questions your code via a warning. See if you can find a way to write the code more correctly, in a more standard way, or more clearly, so that the warning disappears.

    Tom Harris

    August 23, 2006 at 11:44 pm

  3. […] the code is written clearly, and by that I mean that it’s readable, with meaningful variable names and the proper levels of abstraction, then the second step might be to actually read through the […]

  4. I like a lot your coding standard.

    I always compile C code with at least gcc -Wall flag and remove all warnings that appear.
    Then I try also with -Wextra, but I am not always removing the warnings that appear with this flag.
    As stated in the GNU Coding Standards: you decide, don’t be an slave of your compiler.

    David

    April 19, 2009 at 11:59 pm


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s