Code formatting: is lining up similar lines ok?

Question

I recently discovered that our company has a set of coding guidelines (hidden away in a document management system where no one can find it). It generally seems pretty sensible, and keeps away from the usual religious wars about where to put '{'s and whether to use hard tabs. However, it does suggest that "lines SHOULD NOT contain embedded multiple spaces". By which it means don't do this sort of thing:

foo    = 1;
foobar = 2;
bar    = 3;

Or this:

if      ( test_one    ) return 1;
else if ( longer_test ) return 2;
else if ( shorter     ) return 3;
else                    return 4;

Or this:

thing foo_table[] =
{
  { "aaaaa", 0 },
  { "aa",    1 },
  // ...
}

The justification for this is that changes to one line often require every line to be edited. That makes it more effort to change, and harder to understand diffs.

I'm torn. On the one hand, lining up like this can make repetitive code much easier to read. On the other hand, it does make diffs harder to read.

What's your view on this?

Answer 1

2008: Since I supervise daily merges of source code,... I can only recommend against it.

It is pretty, but if you do merges on a regular basis, the benefit of 'easier to read' is quickly far less than the effort involved in merging that code.

Since that format can not be automated in a easy way, the first developer who does not follow it will trigger non-trivial merges.

Do not forget that in source code merge, one can not ask the diff tool to ignore spaces :
Otherwise, "" and " " will look the same during the diff, meaning no merge necessary... the compiler (and the coder who added the space between the String double quotes) would not agree with that!

2020: as noted in the comments by Marco

most code mergers should be able to handle ignoring whitespace and aligning equals is now an auto format option in most IDE.

I still prefer languages which come with their own formatting options, like Go and its gofmt command.
Even Rust has its rustfmt now.

Answer 2

I'm torn. On the one hand, lining up like this can make repetitive code much easier to read. On the other hand, it does make diffs harder to read.

Well, since making code understandable is more important than making diffs understandable, you should not be torn.

IMHO lining up similar lines does greatly improve readability. Moreover, it allows easier cut-n-pasting with editors that permit vertical selection.

Answer 3

I never do this, and I always recommend against it. I don't care about diffs being harder to read. I do care that it takes time to do this in the first place, and it takes additional time whenever the lines have to be realigned. Editing code that has this format style is infuriating, because it often turns into a huge time sink, and I end up spending more time formatting than making real changes.

I also dispute the readability benefit. This formatting style creates columns in the file. However, we do not read in column style, top to bottom. We read left to right. The columns distract from the standard reading style, and pull the eyes downward. The columns also become extremely ugly if they aren't all perfectly aligned. This applies to extraneous whitespace, but also to multiple (possibly unrelated) column groups which have different spacing, but fall one after the other in the file.

By the way, I find it really bizarre that your coding standard doesn't specify tabbing or brace placement. Mixing different tabbing styles and brace placements will damage readability far more than using (or not using) column-style formatting.

Answer 4

I never do this. As you said, it sometimes requires modifying every line to adjust spacing. In some cases (like your conditionals above) it would be perfectly readable and much easier to maintain if you did away with the spacing and put the blocks on separate lines from the conditionals.

Also, if you have decent syntax highlighting in your editor, this kind of spacing shouldn't really be necessary.

Answer 5

There is some discussion of this in the ever-useful Code Complete by Steve McConnell. If you don't own a copy of this seminal book, do yourself a favor and buy one. Anyway, the discussion is on pages 426 and 427 in the first edition which is the edition I've got an hand.

---

Edit:

McConnell suggests aligning the equal signs in a group of assignment statements to indicate that they're related. He also cautions against aligning all equal signs in a group of assignments because it can visually imply relationship where there is none. For example, this would be appropriate:

Employee.Name  = "Andrew Nelson"
Employee.Bdate = "1/1/56"
Employee.Rank  = "Senator"
CurrentEmployeeRecord = 0

For CurrentEmployeeRecord From LBound(EmployeeArray) To UBound(EmployeeArray) 
. . .

While this would not

Employee.Name         = "Andrew Nelson"
Employee.Bdate        = "1/1/56"
Employee.Rank         = "Senator"
CurrentEmployeeRecord = 0

For CurrentEmployeeRecord From LBound(EmployeeArray) To UBound(EmployeeArray) 
. . .

I trust that the difference is apparent. There is also some discussion of aligning continuation lines.

Answer 6

Personally I prefer the greater code readability at the expense of slightly harder-to-read diffs. It seems to me that in the long run an improvement to code maintainability -- especially as developers come and go -- is worth the tradeoff.

Answer 7

With a good editor their point is just not true. :)

(See "visual block" mode for vim.)

P.S.: Ok, you still have to change every line but it's fast and simple.

Answer 8

I try to follow two guidelines:

1. Use tabs instead of spaces whenever possible to minimize the need to reformat.

2. If you're concerned about the effect on revision control, make your functional changes first, check them in, then make only cosmetic changes.

Public flogging is permissible if bugs are introduced in the "cosmetic" change. :-)

---

2020-04-19 Update: My, how things change in a dozen years! If I were to answer this question today, it would probably be something like, "Ask your editor to format your code for you and/or tell your diff tool to ignore whitespace when you're making cosmetic changes.

Today, when I review code for readability and think the clarity would be improved by formatting it differently, I always end the suggestion with, "...unless the editor does it this way automatically. Don't fight your tools. They always win."

Answer 9

My stance is that this is an editor problem: While we use fancy tools to look at web pages and when writing texts in a word processor, our code editors are still stuck in the ASCII ages. They are as dumb as we can make them and then, we try to overcome the limitations of the editor by writing fancy code formatters.

The root cause is that your compiler can't ignore formatting statements in the code which say "hey, this is a table" and that IDEs can't create a visually pleasing representation of the source code on the fly (i.e. without actually changing one byte of the code).

One solution would be to use tabs but our editors can't automatically align tabs in consecutive rows (which would make so many thing so much more easy). And to add injury to insult, if you mess with the tab width (basically anything != 8), you can read your source code but no code from anyone else, say, the example code which comes with the libraries you use. And lastly, our diff tools have no option "ignore whitespace except when it counts" and the compilers can't produce diffs, either.

Eclipse can at least format assignments in a tabular manner which will make big sets of global constants much more readable. But that's just a drop of water in the desert.

Answer 10

If you're planning to use an automated code standard validation (i.e. CheckStyle, ReShaper or anything like that) those extra spaces will make it quite difficult to write and enforce the rules

Answer 11

You can set your diff tool to ignore whitespace (GNU diff: -w). This way, your diffs will skip those lines and only show the real changes. Very handy!

Answer 12

We had a similar issue with diffs at multiple contracts... We found that tabs worked best for everyone. Set your editor to maintain tabs and every developer can choose his own tab length as well.

Example: I like 2 space tabs to code is very compact on the left, but the default is 4, so although it looks very different as far as indents, etc. go on our various screens, the diffs are identical and doesn't cause issues with source control.

Answer 13

I like the first and last, but not the middle so much.

Answer 14

This is PRECISELY the reason the good Lord gave as Tabs -- adding a character in the middle of the line doesn't screw up alignment.