Ivan

Programming in the small - formatting.

Following on from the previous article in the series, another "programming in the small" thing that I look out for is formatting. Good formatting helps make the code easier to read - bad formatting does the opposite.

Formatting should match structure.

Consider the following code:

	public void foo(){
		if(someCondition())
			doSomething();
			doSomethingElse();
	}

At first glance, it looks like doSomethingElse() is only executed if someCondition() is true. However,
it is executed no matter what the value of the condition is. Possibly the code was originally:

	public void foo(){
		if(someCondition())
			doSomething();
	}

and someone had to add doSomethingElse() to be executed after doSomething(). This is why I prefer to always use the {}s even when syntactically redundant.

In Python, the indentation of code is significant - personally, I like this - some people hate it. The reason I like it is because I think code should be formatted with indentation that matches the logical structure of the code, and by making indentation significant, Python enforces this, while at the same time removing the necessity for syntax to delimit code blocks (e.g. {}s or end or equivalent keywords.

Formatting shouldn't waste space

I prefer formatting that doesn't use too much space - in particular, vertical space. Even large screens don't allow for loads of lines vertically. Generally, methods/functions shouldn't be that long anyway, but by using vertical space wisely, you can see more code (e.g. several methods) in one screen without compromising readability.

In particular, multiple blank lines (instead of just one), or blank lines that do nothing for the readability of the code, drive me a bit nuts. I also prefer not to have symmetrical {}s - i.e. not having { on a new line, because I don't think it adds anything to readability (if indentation is correct) but just takes more vertical space. (I just found an article which names different bracing styles - apparently, the style I favour is called "K&R").

When talking about formatting with Romilly Cocking he mentioned about the fact that our vision requires things that we read to be within quite a small region of our field of view - (see macula) - and for that reason it's best to try to keep code reasonably compact. (I hope I've represented what Romilly said - hopefully he'll blog about it.).

Formatting doesn't have to be perfect, but shouldn't be sloppy either

Obviously sloppily formatted code shows a lack of care of code quality - which can be distracting. On the other hand, minor formatting inconsistencies - that is, ones that you have to look for (e.g. using an automated tool) - are probably not worth looking for. In general, if in doubt about formatting, I recommend that the team finds an automated formatter (typically whatever is built in to your IDE) that you can run on your code if you want. However, I wouldn't have code always auto-formatted because that doesn't always do what you want, and I think sometimes you should "get over" minor inconsistencies, but take more important formatting issues seriously.

I'll tell you what I want, what I really, really want.

I'd like developers to take care over the appearance of code, as well as the contents. It's not the most important thing, but it is important.