The Iron Fist Coding Standard

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.

15 comments ↓

#1 Entity on 09.20.10 at 4:00 pm

I think the whole indenting - space issue is just a red herring, and a smelly one at that.

If you want to inforce a tab or indenting between editors and different IDE's you're better off to get the IDE to insert spaces instead of tabs.

Though some people may cry out because of this, but if you have to read a web page about the advantages or reason for tab/space and alignment just stick with spaces instead it just wastes a huge amount of time.

The whole tab->Indent goes back to the old printer days where the tab was used as a special character to move the printer head a set margin on the page. Of course enginners dont talk to other enginners or there is not a standards body design for this stuff. So we have a situation where indent now is 3 spaces vs 4 spaces and the whole mess that comes with it.

Use space or automatically insert a space when you press [tab] and be done with it. It makes copy and pasting code between projects easier and to a point the physical screen representation is what will be printed in a email or printed on paper.

Done.

#2 Entity on 09.20.10 at 4:19 pm

More to the point (Rant ahead)

I think a lot of these problems come from the old technologies that will forsaken be with us to our dieing days.

For example, the wonderful world of a new line.

In Win32, its Carriage Return + Line Feed

In Linux/Unix, its just Line Feed the carriage return is assumed to be there and removed because of redundancy.

In Apple, it was Carriage Return, then later on with the move to OSX it was converted over to Line Feed.

Then we have the programming languages.
In C could run on any operating system, the designers got the C Runtime to output the necessary New Line Character hex values for that format.

So, they took the 'Line Feed' hex value '\n' and renamed it in the C language 'New Line Character', in which case depending on the C run-time or where the hell it was compiled it would convert the 'new line character' to the co-responding 'new line' characters for that platform eg.. PC,OSX,Linux

Where Am I going with this. Well, its just a complicated mess of old conventions that was used in the old days of electronic type writers and major IBM printers that used some 'insert' convention that due to market forces became adopted into technology. Such you have the same *&&* situation with Tab vs Spaces all freaken over again. It wastes a HUGE mount of time, where it DOES not matter.

Just use, auto insert Tabs to Spaces and have a company wide policy how alignment should work using spaces within the organization. It means no matter what text editor you open it up in, the formatting of the text will be the same, where if you use (Tab) you will be burnt for all eternity of time.

#3 Anton Kovalenko on 09.20.10 at 11:01 pm

Tabs may be fine too. Even a mix of tabs and spaces may be fine when done wisely: see http://www.emacswiki.org/emacs/SmartTabs . YosefK, great as usual, took care to include the only sensible requirement for indentation and *not* restrict it to some drivel like "Tabs considered harmful", "Spaces are WRONG" and the like.

All three variants (tabs, spaces, both with SmartTabs) are just great. Spaces look the same way everywhere, and it's great. Tabs cater to preferred indentation width of each reader, and it's great in another way. Smart tabs separate indentation and alignment logically, allowing non-block alignment AND flexible indentation settings at the same time. For each of these things to work, IDE/editor used by each developer has to support it, or indentation will sometimes break. There is nothing more "automatic and simple" about expanding tabs than about converting tabs to spaces or indenting with smart tabs. When a lot of different IDEs are in use (or someone just HAS to use an IDE with a dumb editor for its unique features), spaces-only may be the "lowest common multiple" supported everywhere; "spaces and no tabs" is the right thing in this environment, but not necessary The Only Right Thing Forever.

As of pseudo-commented-out dead pieces of code and the like: unfortunately, novices used to start programming without version control and discover it only after some years of managing to get away without it. VCSless experience makes them paranoid about irreversible code changes, and it takes some conscious effort to get over it. It seems that version control is more common / more mainstream these days (even non-programmers track interesting projects with VCS), so I hope that future programmers won't be afraid of code deletion from the very start.

#4 Yossi Kreinin on 09.20.10 at 11:14 pm

Actually I prefer tab expansion as recommended in the page I linked to but bug someone with an iron fist to expand their beloved tabs when everything looks right everywhere it should I would not.

Commented out code sometimes serves as a useful comment ("or we could do it that way, see, in which case…" or "if you want to compute this also, which we now don't need, this is how you do it") so you may want to keep it regardless of revision control, but then there are those dirty little snippets that could never be useful if commented back in.

#5 sst on 09.21.10 at 4:42 am

The reason I'd do
if (error)
quit();
instead of
if (error) quit();
is one can more easily put a breakpoint on the line with the quit() and this conforms to how a breakpoint is put for multiline conditionals.

#6 Yossi Kreinin on 09.21.10 at 5:01 am

So would I. Wouldn't mandate it though.

#7 Anton Kovalenko on 09.21.10 at 10:45 am

And JWZ is right with his space solution within his solution space. The problem is that there is a kind of tab-lovers he've never listened to (maybe he never run into them?). I'm not of this kind, but I've heard and tried to understand what they propose — and it contradicts to JWZ's `what people care about' list, vehemently.

This kind of tab lovers are after *stopping* fighting wars over 2/4/6/8 indentation by making indentation logical and allowing each developer to use his own preference simultaneously. The idea that some madman *wants* text to look different for different readers eludes space-lovers completely.

Using JWZs "religious" metaphor, w.r.t logical tabs, he looks like a medieval monk never running into a proponent of secular state. "Look, we don't have to fight religious wars anymore, we prefer peace and the rule of law all over the place (oops)." The monk could say something like this: "what people care about is whether they get Shariath or Torah or Biblical law enforced. Then go forth and disestablish secular state, before deciding real issues" …I'd probably side with the monk, after all, (and with JWZ on spaces), *but* I expect the secular tab-lover to have some objections :)

#8 Yossi Kreinin on 09.21.10 at 11:15 am

There's another consideration: the ability to skip over an indentation level/delete one indentation level with a single keystroke - free in most editors if an indentation level is implemented as a single hard Tab character. We're talking deep stuff.

#9 Amir Barak on 09.28.10 at 8:16 am

I had the pleasure of writing code with a guy who not only commented out useless bits of code and left them there but also decided it's a good idea to indent them one step BACKWARDS…

I also think that a good practice is to limit nesting statements in general and [in-function] logic branches specifically.

How do you feel about color schemes? :P

#10 Yossi Kreinin on 09.29.10 at 12:33 am

I saw more than one otherwise great programmer who didn't indent upon nesting - hence the explicit rule.

Limiting nesting statements is generally good just like limiting the amount of calories per meal or something - never felt the need to mandate anything here though.

Color schemes - like syntax highlighting? Feel great about those, colors are scientifically proven to cheer people up or so I heard - obviously never felt the need to mandate anything here though.

With coding guidelines, less is more.

#11 Aleksey on 12.08.10 at 10:33 am

A tidbit about deviations:

When measuring test code coverage single line statement

if(x) panic();

vs

if(x) {
panic();
}

will improve the numbers without sacrificing quality of the test

#12 Yossi Kreinin on 12.10.10 at 6:12 am

This reminds me why I don't particularly like code coverage measurements.

#13 a nony mouse on 10.21.11 at 7:15 pm

* respect what has come before
* be respectable

Joel Spolsky said something like that, IIRC.

#14 sh on 06.21.12 at 4:32 am

The profanity link did not explain why "it is easier to write", but it sure is funny.

#15 Yossi Kreinin on 06.21.12 at 10:44 am

Profanity was shown to increase the ability of subjects to sustain pain. The link shows, mostly, pieces of code that were clearly painful to write, and profanity in the comments and identifiers, most likely, made writing it easier.

Leave a Comment