Rant: The Evils of Indentation (FREE STUFF If You Prove Me Wrong!)

Do you indent your code for good or evil? Of all the horrors that
afflict the pilgrim programmer, evil indentation is the most
horrific. The horrifying lack thereof, the horrifying use of tabs, the
horrifying concoction of tabs and spaces, the … well, read on fellow
coder, and face the horror yourself!

But first, ask yourself one question: why do we indent? why do we
bother? What is it in our very nature that makes indentation the
first principal of coding?

Source code is all about structured logic. When you make it easy to
see the logic, then the program is easy to read. That's why we
indent. The first, foremost and only reason: it makes code easier to
read. All else follows.

That's why I really have to wonder when I see badly-indented code. Do
these coders care nothing for the ethics of the profession? How can
they so callously cast these cancerous texts upon us? Do they care
nothing for themselves? Will they not have to maintain these corrugations, six
months hence? Do they secretly enjoy
all-nighters and death marches? Perhaps…

So, in the interests of the programmer-on-the-street, I hereby lay down
the evils of indentation. A how NOT to do it guide, if you
will. If you have never consciously considered these great questions
before now, if you have simply followed the pathetic example of your
peers, the perilous proclivities of your peripatetic tutors,
or the prescriptions of your workplace, then think now, or forever hold yourself back.
Indentation is a detail that has to sweat.

⋅ ⋅ ⋅ 
   
⋅ ⋅ ⋅ 

Here then are the evils of indentation. There's a suitably evil number
of them: four.

The First Evil: To Tabulate

for( fs = 0; fs < sake; fs++ ) {
        thisIsNuts();
        if( mindcapacity < nineitems ) {
                fire();
        }
}

Evil Typewriter
Hey, you know what? Tabs were invented for typewriters. In the
modern software development environment, the tab key stands for only
one thing: move this line of code to the correct indentation. It does
not mean: insert a tab character. Just because you have tabs
set up to show as four spaces as a kludge, does not mean that that the rest of the
programming world thinks this is a good idea.

Tab characters will show up differently all over the place. The whole
point of indentation is lost if the indentation is not the same for
all developers on the project. Think of the children! For goodness
sake stick to spaces. Every time you hit tab your IDE should insert
the correct number of spaces to bring your code to the current
indentation column. And that's it. Nothing fancy. But now, guess what?
It looks the same for everyone. Do you realise how many lives you just
saved? How many premature heart attacks you prevented?

The Second Evil: To Make Too Much Space

public void removeContext() {
    if( spacedOut() ) {
        line >>> allthewayover;
        meaning = inview ? ok : emptyspace;
    }
}

Evil Space
So you like to indent by four spaces. Sure. Are you nuts? what a waste
of screen real-estate. One of the biggest aids to program
comprehension is ... code on the screen. Yup, the more code you can
see the better. Get a bigger monitor and see the difference. So with
your IDE of choice squashing the code window from all sides, you really
need to avoid pushing code off to the right. It just disappears out of
sight and out of mind.

So keep it to two spaces. Always and forever. There is no other way to
optimise this. One space is not clear enough. Three spaces is
bizarre. Four is wasteful. Anything more, like say, eight (Some people
actually do this - God help us all), and you should be fired for
wasting bytes.

OK, I'll relax a bit. Sometimes you can use four spaces to
indent. When there is a substantial change of context, for example,
anonymous inner classes (they are freaky enough to warrant their own
rule, don't you think?), then it makes sense. It's a good visual clue
that something a bit different is going on.

The Third Evil: To Stray From The Path

if( logic ) {
    canbefollowed();
  } else if( logic ) {
isclear();
} else {
    runaway();
}
  crying();

Evil Path
So you've changed the settings on your IDE, you use two spaces, tab
inserts two spaces, and auto-indents to the correct level, and you're
sitting pretty. Not so fast, flyboy.

You are indenting everywhere right? And I mean,
everywhere. There is no point doing it in a few places and getting
lazy when you do your usual cut-and-paste coding anti-pattern. Or you
make some changes to code that was written by someone else and you just,
ignore the indentation. Sure it's only here and there. Bzzzt!
can you say spaghetti code?

Stick to the one true path: indent everything, and never mix tabs and spaces.

A
foolish consistency may be the hobgoblin of little minds
, but
you're not writing poetry, you're writing code. Get a small mind. A
really really teeny-weeny tiny one. Get obnoxious about consistency and
the coding brethren (that's a gender-neutral term, by the way) will thank
you! Come on, neat code just makes your day.

The Fourth Evil: To Break The Bond

public void myProfessor()
  {
    toldMe();
    if( makeCodeReallyReallyClear() ) 
      {
        thenIAmGood();
      }
    else
      {
        actuallyIAmWasteOfSpace();
      }
  } 

A Good Bond
So this one is a bit of thrown gauntlet. Here's the question: what does each level of
indentation signify? Well? It's not hard...

One level of logic. Just one. Not two. One. Each level of indentation
says we've gone a one level deeper into the decision structure. There is an
intrinsic bond between indent and logic. Keep to this
rule and your eye can scan the code and see that it is good. You can
pick out the flow of the code from 300 yards and hit
the target with your back turned using a mirror
.

So why, oh why, do some people find it necessary to indent two
levels, wasting a line into the bargain? Not a chance you can
justify this. Maybe someone took a beginners design course where they
were told that whitespace was good. Sure it is. But, you know, all
things in moderation...

⋅ ⋅ ⋅ 
   
⋅ ⋅ ⋅ 

Come on people! There are no excuses. Most source editors will auto-indent
for you anyway. Let's get with the program and remove this root of
programmer pain. We have enough to worry about with demanding
managers, impossible deadlines and long hours. Let's just do each
other a favour.

In case you think I'm all talk and no action, here's the action. You
can scour my code for indentation evils. I have an open source
project, Jostraca,
that's been around for about five
years and has had plenty of time to build up a bit of cruft in the
codebase. So get going! Everybody who finds a violation will get a FREE
CSV Manager
single developer license, worth $97. Oh yes, that's real money.

Here are the rules: you have to be the first to find and post the
example of incorrect indentation in the comments to this entry. You
have to state which evil is being perpetrated. If you're second
fiddle, tough luck. The example has to be taken from the latest
release (1.4.0). Generated code and non-Java code don't count so don't
bother looking there. Oh, and I reserve the right to
invent new rules if I feel like it.

So come on, are you gonna bankrupt me for mouthing off or what?




This entry was posted in Rant. Bookmark the permalink.

2 Responses to Rant: The Evils of Indentation (FREE STUFF If You Prove Me Wrong!)

  1. Koejex says:

    Tabs versus Spaces is an irsinetteng style choice. I have always used spaces for my indentation, although, recently I wondered why. In the last few years I often had to deal with code from many developers who all used their favourite (and different) code editors. These code editors were set to indent code in their own way and to automatically format code using their own rules. Once the code passes through a few of these developers the end result would often be an unreadable mass of code embedded around a mismatch of white space. Now, my general thoughts in these occasions would be that the Space character finite. The editor cannot format a Space incorrectly. Of course, if you actually think about it, the real problem was consistency in the coding style amongst the developers. There were no rules governing these aspects of the code formatting.Things have improved a lot, but in this particular environment a project would often originate externally and then there would not be time to refactor the code base to conform to our standards. The moral of the story is to have a strong enforcement of the chosen coding standards for your business. This is code some poor developer is going to have to maintain.

  2. Truly enlightening… looking onward to coming back

Leave a Reply

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