This is a post in my series on things I've remarked on in code review.

Gestalt theory deals with how we perceive things. It is perhaps best known for its laws of visual perception: for example, the Law Of Proximity states that we "perceive objects that are close to each other as forming a group" (Wikipedia).

We all unconsciously apply the Law of Proximity when we read code, so I try to do so consciously when I write it.

For example, instead of

def my_method
  return if foo
  # Info about bar.
  return if bar

  baz
end

I would prefer

def my_method
  return if foo

  # Info about bar.
  return if bar

  baz
end

so that the comment and the code it applies to form a group of their own.

I would especially steer clear of

def my_method
  # Info about bar.
  return if bar
  return if foo

  baz
end

In this example, the Law of Proximity suggests that the comment applies to both bar and foo, but it's only intended to apply to bar.

Similarly, a comment that applies to several paragraphs of code would suggest the wrong grouping if it's right next to the first paragraph:

# Info about foo and bar.
foo(1)
foo(2)

bar(1)
bar(2)

Instead, I'd do

# Info about foo and bar.

foo(1)
foo(2)

bar(1)
bar(2)

There's also horizontal proximity. Instead of

foo # Info about foo.

I prefer

foo  # Info about foo.

with two spaces, so the comment and code are more clearly separate.

With syntax highlighting, this horizontal separation is less important – per another law of Gestalt theory, the Law of Similarity, the different colors help us separate code from comment. Still, every bit helps.