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();
        }
}

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;
    }
}

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();

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();
      }
  } 

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?

I just got my copy of Entrepreneur Focus, a new book on starting-up companies by Eric Locken. He asked me to do an interview for the book about my experiences starting Ricebridge, so with an ego the size of a planet, how could I refuse?

Here's a transcript of the interview.

There are a load of other great stories in the book. Go check it out if you're into startup tales.

It will kill your CPU, but here's the classic Game of Life, ... in JavaScript! It is possible, Your Honour!

You known that IntelliSense rots your brain, right?

Well if you use Emacs, now you too can rot your brain, only better (everything is always better with Emacs).

This is the most treasured snippet from my .emacs file. All it does is store every word in all open files and when you hit tab, it autocompletes based on the text before the cursor. Sure, it doesn't show you the list of possible candidates, but all you ever need is a few tabs and you'll find what you want.

; auto completion
;;;;;;;;;;;;;;;;;
(require 'dabbrev)
(setq dabbrev-always-check-other-buffers t)
(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_")

(global-set-key "\C-i" 'my-tab)

(defun my-tab (&optional pre-arg)
  "If preceeding character is part of a word then dabbrev-expand,
else if right of non whitespace on line then tab-to-tab-stop or
indent-relative, else if last command was a tab or return then dedent
one step, else indent 'correctly'"
  (interactive "*P")
  (cond ((= (char-syntax (preceding-char)) ?w)
         (let ((case-fold-search t)) (dabbrev-expand pre-arg)))
        ((> (current-column) (current-indentation))
         (indent-relative))
        (t (indent-according-to-mode)))
  (setq this-command 'my-tab))

(add-hook 'html-mode-hook
          '(lambda () 
             (local-set-key "\C-i"     'my-tab)))
(add-hook 'sgml-mode-hook
          '(lambda () 
             (local-set-key "\C-i"     'my-tab)))
(add-hook 'perl-mode-hook
          '(lambda () 
             (local-set-key "\C-i"     'my-tab)))
(add-hook 'text-mode-hook
          '(lambda () 
             (local-set-key "\C-i"     'my-tab)))

; add more hooks here

The code isn't mine and I can't remember where I found it, but it has saved me countless hours of typing.

Another good one from Bruce: SETI virii.

Reminds me of the "negotiating with host" bit in Independence Day. Strange how the virus isn't evil when we're the good guys.

One thing about my current theme that was really annoying me was that my trackback URLs were pushing into the sidebar. Roller trackbacks are faily long, and there's no way I was going to go mucking about with the code making them shorter.

So then I remembered that the fancy new Google Analytics system does something nice with URLs that are too long. If you set overflow:hidden on the div, then the URL is cropped if it gets too long, but you can still select the entire thing – the div scrolls when you select text, and double clicking works too.

At first I started editing the roller template, but that is the wrong way. Just edit the div.trackbackUrl style in your stylesheet instead.

More roller hacking.

So it looks like I'm not the only one who's a bit annoyed about crappy API documentation.

Even Microsoft can't get it right. And I'm not surprised. How many Microsoft developers have been on a creative writing course? Something to think about Bill.

Like I said before, API documentation is hard problem. The only way to produce good API docs is to get the developers to write good copy. No two ways about it. It's a good skill to have and something that should be encouraged. And yes, I know, it's damn hard.

Back to the doctor today, I had to get a mole removed. They can't enough of me.

The worst thing about minor surgery is the fact that you are conscious. Of course, the drugs are great and work really well (and amazingly quickly), but you still feel all the tugging and pulling.

The irish health service may have it's share of problems at the moment, but the people who work in the service are really excellent. I've met a lot of them this year and the standard of care once you get admitted is really great. I do think that the (traditional) media does it's usual trick of highlighting bad news. Like any organization, most workers are just trying to do a great job despite all the bureaucratic silliness.

Getting a health service to work efficiently is a really hard optimisation problem. It's not just about money – you have to get the standard of care right. It's not even a straightforward problem of deciding on priorities because a lot of your resource allocation has to be done on the basis of ethical criteria. I studied moral philosophy in an earlier life and, hey, it's one hot cookie.

Anyway, I am not going to offer some half-baked opinion on how to do things right. How did we end up with effective market economies in the first place, the kind that work out OK for most citizens? The ancient greeks put a whole lot more thought into it than we ever did, and we just happened to stumble upon an idea that really worked, almost by accident. So the default strategy as regards health care should really be to keep trying to find new solutions. There has to be a few "good enough" local maxima somewhere in there, and we may even hit the big time.

An important and serious contribution to the advancement of the mathematical sciences.

A new kind of ringtone!

So this weekend myself and the family, big culchies that we are, are off to the Dundrum Town Center (pathetic flash site - hello guys, HTML please) for a gawk. This is Ireland's latest and greatest "mall", which includes a Harvey Nicks, and a Sony Centre.

Hold the phone?

A Sony Centre? Well, like any gadget-geek-freak programmer I was just gonna go wild buying stuff! Not any more. You know why.

By the way, if you're still buying stuff from Sony, shame on you.

And if you think the little guys can't make a difference, think again. I'd like to show you something. When the SCO thing was just starting, many moons ago, I wrote some emails to companies that were selling SCO, informing them of my, er, distaste for their behaviour. Here's a sample:

Dear Sir/Madam,

I am an independent software consultant and I notice
that you are a reseller for The SCO Group.

As I am sure you are aware, The SCO Group has made
baseless claims to own the Linux Operating System.
Such claims have already been withdrawn by SCO in
Germany by court order.

I'm afraid that so long as [NAME DELETED] continues to
support the actions of The SCO Group by providing a
sales channel for them, I will refrain from recommending
your other products and services to any of my customers.

Yours Faithfully,
Richard Rodger.

-----------------------------------

Dear Richard,

Thank you for your email.

Unfortunately we have never heard of you, therefore, we are
unaware of the effect this will have on the worldwide sales of SCO software.

Kind regards,
[NAME DELETED]

And where is SCO now? Bet you've changed your strategy. Lot's of little guys that you have never heard of can be quite noisy.

If big companies do nasty things, complain! They need your money to survive you know.

Oh and in case you think I'm some sort of free software nut, I have my own software company, and I sell software for a living, and I rely on copyright laws to do that.

So this post is part of my continuing series on hacking Roller.

I use the textile plugin when typing up most entries as it saves on the amount of typing you have to do. If I'm going to write up pure HTML I'll do that in Emacs thanks very much.

But the textile formatter has a really annoying bug – it messes up apostrophes! They end up the wrong way round, rather just the normal old ASCII character, which is what I want. So into the source we go. The textile formatter source is available from sourceforge.

It turns out that it's all done with regular expressions, so I just disabled the relevant ones in the Textile.java file, and jarred up a patched version.

With my local JDK 1.5 compiler. And tried to run it on the server (JDK 1.4). Oh Joy. Website down. Remember to use the source and target options when you try this at home. Tomcat is such a pain to restart. Actually I wrote a neat little Tomcat restart script, expecially designed for data-center staff with no patience. I must post it sometime.

Anyway, if the apostrophes in this post are still wrong, I will cry.

Oi! Kansas! You know who's having the biggest laugh at you? The Big Man himself.

Hey didn't you guys try to redefine PI at one stage as well?

Microsoft's new extension to RSS is a pretty big deal. Now normally I would roll my eyes at yet another attempt to smother an open standard, but this time it's actually not so bad.

You know an idea is in the air when many people are coming up with it independently. The idea that I'm taking about is micro-content. We have a lot of different people working on this at the moment, and RSS has shown the way. Even that new database thing by that annoying startup is all about micro-content.

I've been working on some ideas for a micro-content "broker". A piece of the infrastructure that makes it easier to synchronize and exchange micro-content items. Now, I knew that Lotus Notes had some cool synchronization algorithms, and that Ray Ozzie had probably had a hand in bringing a few of them over to Groove. I wanted me some of that action, but it was all tied up in the proprietary code.

So what has Ray gone and done? Only spec'ed out a working version of the synchronization algorithm! Way to go! And it's politically correct and all, using a Creative Commons license. This is gonna be big.

You're not going to like this.

Tom Evslin points out that APIs will make or break most of the new web applications. And he's dead right. In fact, API's are where all the really interesting stuff happens, because you get people doing things with your service that you never dreamed of.

Now we're talking specifically about web service APIs here. Because it's the network effects that make the magic. Metcalfe's Law, Reed's Law, even Godwin's Law. Take your pick. So these days, any sensible web services entrepreneur is going to want to get an API on the boil sooner rather than later.

Now I've been doing some work with the "big" APIs, like Google, Amazon and friends. I'm building a set of examples for my new product (due out shortly). One thing I will say is, go REST young man! SOAP interfaces are the suck. They raise the bar to entry far too much. Heck, do you realise that most people not only do not understand XML Namespaces, but are actually afraid of them? Too many nooks and crannies. Too much to go wrong. Amazon, for example, seems to change their namespace on a regular basis – it's date based. What a pain.

The other thing about APIs is that they are very very hard to design and maintain. I've run into this issue quite a bit with my Java Components. It is basically impossible to fix a broken API after the fact, but version 1.0 of anything useful still has far too much complexity to get it all right the first time. Actually, I took an approach to this problem based on some ideas by David Bau, which has worked out quite well. All the callback interfaces in my components use an intermediate abstract class to provide a DMZ for future changes. I've already used this succesfully to fix some problems, without any users having to recompile.

So how can you apply this to web services, where there is no inheritance model? The most important thing is to ignore what you don't understand. HTML is the classic example of this. The second thing is that you must support until death-do-us-part all your declared objects, methods, values and properties. You just gotta. Think real hard about them before you publish them. It's very difficult to get right, but that's programming for you – not as easy as it looks. And finally, don't reinvent the square wheel. You absolutely, positively should look at what other people are doing, how it's worked for them, and what you can do better. Build a Toyota, not a Trabant.

I predict (OOH, dangerous sir!) that a market will develop in helper applications and third party API providers for websites and services. In fact, you can appize (you heard it here first: [æp'aiz]) any site, if you really want to – just look at all the blogification (OK, I'll stop now) going on. So, start your motors gentlemen! We've just got ourselves a new business model.