I’m a stickler for formatting. Code should look elegant and it should be easy on the eyes.

When I see how some code is formatted I think ‘Why do you even bother? What are you trying to accomplish?’ Which brings me to a good point: what are we trying to accomplish with formatting our code?

Back around 1985 a bunch of us COBOL coders were let loose with C, we were like ‘Oh, wow, now I can do ___’ and we wrote a dozens of tools, games and toys. Steve, my co-worker, wrote a tool that would strip out all unnecessary whitespace from a C source code file, that included Line Feeds and Carriage Returns, and produce a very compact and nearly unreadable but valid and compilable program file. This was mostly an exercise in programming but brings up a good point: ‘Why format code?’ What is the purpose?

Later in the 80’s we hired a new C programmer and he sent samples of his code. He used the format where an opening curly brace was below the block’s keyword (e.g. if, while, for, struct) instead of at the end of the line with the keyword (AKA “K&R style”). We looked at this and instantly and inarguably realized it was better and changed our standard. I wrote an editing macro and updated all of our source code files within minutes of seeing this better style.

Our old (“K&R style”):
for (i = 0; i < max; ++i) {
    printf ("%d\n", i);
}
The new style:
for (i = 0; i < max; ++i) 
{
    printf ("%d\n", i);
}

This all leads to the answer: better communication. The new style makes it easier to match the start and end braces, especially when you have many nested levels of blocks within blocks. It makes it clear what is going on.

Today when I see bad formatting I get the idea the Programmer writing it didn’t care about making it readable. It is a mark against them.

Over the years I’ve developed some rules for my code style/formatting:

  • Never more than one blank line. When you start using more than one blank line the question comes up ‘When do you use two?’, ‘When do you use three?’ A blank line is used to separate one section from another and two blank lines doesn’t separate the two sections any more clearly than one. Let me make this clear: NEVER MORE THAN ONE BLANK LINE AT A TIME, and give careful consideration to using even one.
  • My comments are sparse and important so I include a blank line before most comments.
  • I always use braces to specify a block even when it isn’t absolutely required. Some modern languages (Swift?) require braces for all code blocks and others rely on just indention to demarke blocks.
  • End braces do the job of separating code very well so I never have blank lines before or after an ending brace.
  • Use tabs for indents, not spaces, this keeps blocks that are indented aligned. There are pro’s and con’s for using both spaces and tabs but tags make it quicker to un-indent a block or line of code.
  • Keep the rules uniform. No ‘double tab for sections that aren’t likely to execute’ type rules.
  • Good rules fit all situations.
  • I tend to spread things out vertically. I don’t want to miss something just because the line of code extends beyond the right edge of the window. In the old days the window was 40 rows of 80 columns, and that was all, that was it but now with high resolution monitors a sub-window is often well over 150 characters wide, and still lines run off the right edge.
  • At the very least don’t do whacky indents/outdents that screw up the readability of otherwise good code.

This is just my opinion. My opinion and 36 years of experience working in dozens of different software development shops exposing me millions of lines of code written by hundreds of Programmers. Still, just my opinion.