You are here

guidelines

Code Styleguides

I ambled onto the Coding Style Guidelines for Webkit recently. http://webkit.org/coding/coding-style.html
Reading this ignited in me a desire to voice something that's been gnawing away at me for years now - styleguides, and what it means when they are wrong.

Now of course, styleguides are really just personal preferences enforced to keep code easy to pick up and read for larger teams. Really, if the code works, is readable, is expandable, what difference does it make?

There's also the issue of language. C-inspired languages are easy to compare, but doing so naively can result in misunderstandings. Then of course there are languages such as Python, which I've recently started learning and using for a huge commercial project. The very layout of the language is significantly different to C, which means a different mindset is needed for visual layout.

Anyway, since Webkit got me into this line of thought, I'll pick at its rules to make my points. I'm going to describe how I think C-like languages should be presented. My mind has changed on this over time, and it will in the future. This is not the word of god - except in the literary sense that the word of god has been changed and rewritten over time to suit whatever truth people want to push on others.

1. Indentation.

Don't use spaces. Really. The amount of time spent cursoring over spaces to get to code wastes any benefits from needing to set up your editor to tabs of four space widths.
The indentation required varies with the readability of a language. I've found that classic C is best with three space tabs. Rexx favours two spaces. Java and PHP read easiest in four spaces.
There are no disadvantages of using tabs if you know how to change the width in your editor (and your editor doesn't enforce tab to space conversion - I'm looking at you, PyDev). There are disadvantages to spaces.

2. Switch statements.

Webkits says:

switch (condition) {
case fooCondition:
case barCondition:
    i++;
    break;
default:
    i--;
}

I say, this is unreadable. Use this:

switch( condition )
{
    case fooCondition:
    case barCondition:
        i++;
        break;
    default:
        i--;
}

3. Spacing.

Make it readable. I am starting to think many modern coders have never read a magazine, or have read only American newspapers - which seem to be stuck in the 19th century in terms of presentation. There is no need to fill every space on the screen with code - in fact, it's counter productive. Use whitespace. Whitespace is good (when it's not significant whitespace).
Use existing features of the language, such as curly braces, to promote spacing.

if( mycondition )
{
    doThis( a );
}
else
{
    a = getThat();
}

For the spaces around items in expressions, use common sense. ONLY common sense. Every situation is different.

a = t*4
b = myCall( a*( b*4 ) )
c = longname * something else

Just make it readable. Put spaces where they made sense, take them away when they don't.

For functions and statements, don't make them different on religious grounds. Yes, if() and myfunc() are very different things, but that is obvious and ingrained in a programmers mind and vision.

if( me )
{
    call( that );
}

"if(" is always recognisable as an if. Always.
And 'me' is always me.
"if (" offers nothing of advantage, except to say "I am clever and know 'if' is not a function".
But "(me)" confuses 'me' with parenthesises - they are part of 'if', not 'me'.

4. Line breaks.

Keep things spaced out. As far as possible, keep separate logical steps on separate lines, using your common sense (don't go breaking up 'if' statements..)
This includes braces as far as I'm concerned.

if( this )
{
    doThat();
    andThat();
}

if( this ) { doThat(); andThat(); }

5. On braces.

Always use them, even for one line clauses. This comes down to uniformity, readability and not needing to switch gears in your brain to work with single and multi-line clauses - they are the same things, just with different numbers of lines.
Put them on their own lines - try paging through a thousand lines looking for something with all the code bunched up - the braces enforce whitespace as well as making it possible to visually detect blocks of code. No, indent don't do it - there are too many exceptions where we break indenting rules.

I agree with Webkit that empty code blocks should have empty braces, it's far more readable with less room for mistakes or miss-readings of a fairly uncommon construct:

for( ; i++; );
for( ; i++; ) {};

6. Naming.

I believe Java has it right - use camel case.
Don't usually place a variable's type in its name. But use your common sense - if you have a variable for which it is not obvious, or similarly named variables tracking similar aspects using different types, then mark them out by all means.

The VB style coding of prefixing every variable is ugly.

Subscribe to RSS - guidelines