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.
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.
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.
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.
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.
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.
So would I. Wouldn't mandate it though.
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 :)
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.
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
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.
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
This reminds me why I don't particularly like code coverage
measurements.
* respect what has come before
* be respectable
Joel Spolsky said something like that, IIRC.
The profanity link did not explain why "it is easier to write", but
it sure is funny.
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.
Post a comment