The Iron Fist Coding Standard

September 20th, 2010

I've developed the following coding standard during the years when I've been responsible, on and off, for reviewing code by other programmers. It's suitable for most text-based programming languages and data specification formats.

Rules

Indent upon nesting

Where control structures or data objects nest, indentation helps a reader to keep track of the nesting level.

Indentation should render properly in all relevant IDE/editor configurations. Nobody should see stuff in the inner scope closer to the left than the outer scope. Seriously, spend 10 minutes to understand tabs vs spaces issues.

Use profanity judiciously

Profanity makes code easier to write, but harder to read and modify. Profanity signals a potential hazard, but distracts attention from the details – the opposite of a good warning. With profanity, less is more.

Be careful with comments, more careful with identifiers, and still more careful with the ones going into symbol tables. Except when mandated by an explicit requirement, under no circumstances should profanity appear in a program's output, documentation or configuration files, or be a required part of its input.

Clean up

Bits of code that can't possibly serve a purpose are a sign of neglect, scaring some readers and depressing others. Delete.

Semi-commented-out stuff spread around in moments of panic can be hard to clean up during the bad mood that breeds it. But that bad mood will haunt you as long as you keep bumping into that stuff. So.

Deviations

Concise nested statements or data object specifications can take one line and so need no indentation: if(error) quit.

Indenting upon nesting is neither mandated nor recommended in languages and formats where it is not customary. For example, code following a branch instruction or the <html> opening tag.

It's nice when generated code is indented, but sometimes the white space uses up bandwidth and sometimes you get fed up with propagating the nesting level through the code generator. Generated code is mostly read by whoever wrote the generator so it's up to you.

For profanity to appear in a program's interaction with the user, no explicit requirement is needed when it is a common practice in the given branch of the industry.

Some code won't be very tidy when you're really in a hurry – so be it.

Conclusion

Adopting the Iron Fist Coding Standard will give you the benefits of a mature, field-tested system of coding guidelines while saving the cost of creating one from scratch.