Monday, August 29, 2005

Coding Style - The Rest Of It

WARNING: This blog entry was imported from my old blog on (which used different blogging software), so formatting and links may not be correct.

There are several coding style documents. The primary one is probably the JDK style,
documented here. The problem with that document, and others like it,
is that they leave a lot out.

I found some other useful coding style
documents, but I disagree vehemently with some of their rules (like open braces on a separate line,
and underscore suffixes and fields, and indentation level 2) so instead I will present
my own delta from the "official" JDK style:

So, with the following I'd like to put a stake in the ground, and describe my own
style preferences as additional rules to be added to the JDK style.
I should point out that these aren't rules I've invented - they are rules I've
learned from either discussing with, or reading code written by, developers I admire.

So, without further ado, here are my additional rules:

  • Never use Tabs. Some people like tab characters because it's easy to
    jump back and forth full indentation levels by just pressing arrow left and right over
    these. However, this benefit does not nearly make up for the disadvantages: different
    tools assume different tab sizes, and things get really messy when you have files with
    spaces in some places and tabs in others. Just don't do it.
    This issue has been around for a long time, and I figured the style guide would
    discuss it, but they left it an open issue. Cowards! :-)

  • Never capitalize Acronyms. Yes, unlearn everything your English teacher told you
    about acronyms. Remember, camel cased program identifiers aren't English words anyway!
    For example, HTMLDocument should be named HtmlDocument.
    CSSParser should be CssParser. This makes the code easier to
    read and easier to visually scan. Plus it's prettier.

  • Don't use underscores in variable names. I didn't say Never, since there's one
    exception: for constants, the constant should be fully upper cased, and words separated
    with an underscore, e.g. MAX_VALUE or INITIAL_VELOCITY. But never ever create variable
    names like "max_count" or worse yet, "_count".

  • Don't use Hungarian Notation. This is where you prefix variable names
    to tell you whether these methods are locals or class fields, etc. This makes the
    code less readable (even if you can infer more state from studying the code).
    And uglier. Ugly is bad.

  • Don't put in obvious initialization. This is not a big deal, but again
    in the interest of readable code: don't state the obvious. When you're declaring
    class fields, there's no need to assign booleans to false, references to null, etc.

    private boolean foo;
    private Bar bar;

    instead of

    private boolean foo = false;
    private Bar bar = null;

  • Don't add your initials in comments. Some developers like to leave
    their initials next to comments, e.g. // TN Handle abnormal exit here. People
    from Borland seem especially fond of this. I don't think this is a good habit.
    The comment should be self-descriptive, regardless of who added it. If it represents
    an action that needs to be taken, then add the token "reserved" for this: TODO.

  • Don't use recursion where simple iteration would work. I recently
    came across a code fragment that was simply walking up the parent chain to look
    for a particular ancestor. This was done using recursion! This should be done
    with simple iteration. Iteration in this case is clearer than the "mathematical"

  • Use = foo; for construction field initialization. If your class
    has a property foo, then name your constructor parameter name the same thing, and
    initialize it using the this-pattern shown. Don't use other variations like naming the
    parameter newFoo or worse yet, something involving an underscore in the parameter name!

  • Write debuggable code!. I've seen many people argue that you should use the ternary
    operator (a ? b : c) instead of if-then-else constructs. While the ? operator certainly makes
    for more compact code, this code is often hard to debug, because you cannot easily set breakpoints
    on one condition and not the other, and you cannot easily step to see which condition is taken.
    This is an "issue to consider" more than a "rule to follow" since there are tradeoffs, and
    I use both forms, depending on the context.

No comments:

Post a Comment