Use of Vertical Whitespace

Question

My intention in this question is not to be pedantic, but rather to explore an overlooked axis of an important topic (the use of whitespace). Much debate and care has been put into the use of horizontal whitespace, indenting after a conditional, a space between an if and parenthesis, etc. In fact the issue is considered to be so important and contentious that, not only do some companies have rules and standards for it, but some companies even have rules forbidding it's discussion.

Why is it, considering the state of horizontal whitespace, that the discussion of vertical whitespace is such a dead issue? Why is the x more important than the y? A few days ago I noticed that when I reading code, I, without thinking, often adjust vertical groupings of statements. Having read other peoples code now, with an eye toward vertical whitespace, I noticed several patterns, so I ask stackoverflow:

• What hard and soft rules do you apply to vertical whitespace?
• Are there any vertical whitespace uses that are generally considered very bad, or very good practice?
• Have you found reading code with "correct" vertical whitespace helped in understanding it?
• Does anyone other than typographers and me care?

Answer 1

I certainly care and tend to group code properly (at least for my eyes) with blank lines where appropriate. Ofttimes this means many blank lines but in general I consider the code more legible than with everything crammed together. Just like spaces around operators are a very nice thing so are blank lines around logically-grouped statements.

More than a single blank line at once looks a little out of place, though.

Answer 2

I find it hard to read if code is spaced irregular vertically. I even go so far as to remove braces not required, or if it is short blocks, such as ifs or fors, place it on the same line.

Answer 3

I think one of the most important things is to group a logical step together, such as:

foo.setBar(1);
foo.setBar2(2);
foo.writeToDatabase();

bar.setBar(1)
bar.setBaz(2);
bar.writeToDatabase();

That way, the code is easier to read, and is more descriptive, for me anyway.

Answer 4

If a group of statements is logically related, I give it a blank line before and after. This separation helps if I need to refactor it out into a function later on.

As for double blank lines: If something is that distinct, you should really consider making it a function.

Answer 5

It has been known for decades that a programmer's ability to understand code is generally limited by how much of it he can see at one time. (See for example Weinberg, "Psychology of Computer Programming", an oldie-but-goodie.) In the old days of paper listings, programmers would grab large tables and spread multiple pages of listing. Nowadays, screen real estate is somewhat better than the days of 24x80, but I still tend to minimize use of vertical whitespace, since lots of blank lines take up screen space that could be showing me actual code.

Answer 6

I look at vertical space in code the way I look at paragraphs in written prose. Just as a paragraph is meant to group sentences together that have a common point or idea, lines that are related should be grouped together.

The overall objective is to improve the readability of the code. Just as an article without any paragraphs would be difficult to read, so to is code without any vertical space. And just as with prose, there is a balance between composing paragraphs that are too short or too long. But in the end, it mostly comes down to personal style and preference.

Answer 7

If a comment applies to several lines of code, then I put whitespace after the last of those lines, unless there's other syntax to break things up (like the end of a block).

Anywhere that I'm doing "something" which takes several lines of code, immediately followed by "something else", then I'll either abstract into separate functions or else place comments[*]. So lines of code generally end up grouped together in short blocks, except where the flow-control makes it (in my opinion) self-explanatory.

I do care a bit about whitespace, but actually it's the comments I care about more. If a few lines of code together do some specific thing, and it's not been taken out as a function, then I'd like to see an English description of what that thing is. That way I can see that the "steps" of the function genuinely add up to the right result, then look to see that each step does what it claims to do.

In classes, I sometimes put whitespace between methods/member functions, and sometimes don't. In C++ I put whitespace before access specifiers.

I put whitespace between classes, (sometimes not for anonymous inner classes in Java) and between functions outside classes.

Other than that, my code is pretty vertically dense. I almost never use multiple blank lines, even when separating sections of a header file and the like. I'd prefer blankline-commentline-blankline rather than blankline-blankline, even if the commentline ends up being something completely banal like "helper functions". I dislike styles which have enormous vertical whitespace between functions - if they're so separate that you don't want to see them both on screen at the same time, I'd say either put them in different files or fill the gap with Doxygen/Javadoc comments.

[*] In the version I check in. I usually write code more or less without comments, then compile it, run quick tests, comment it, run proper tests, commit it. That often changes a bit, and sometimes a lot. For instance if I'm coding to an algorithm which is precisely defined in advance, or to a spec where the implementation is "obvious", I might write the comments first and then the code.