Code is for reading

Code is primarily written for programmers to read. Why don't people seem to realise that?

This is a rant I've wanted to have for a while, and have finally been pricked into it by a friend, Andrew Ketley making a comment about writing spreadsheets. He said:

The modern spreadsheet is no longer a simple tabulating and adding machine - it'a a highly sophisticated construction kit for certain classes of corporate applications, and needs to be approached as such....Hardcoded constants, obscure naming, spaghetti logic - it's all there.

Code is primarily written for programmers to read. Often that programmer is you - 5 seconds, 5 days, 5 weeks or 5 years later. Sometimes it is other programmers. If code was not written to be read, then we would all be happily writing in assembler, as the time to write assembler probably isn't that much slower that modern programming languages. What is slower is the time to test it, and modify it, whether those modifications are to add functionality, change functionality or remove bugs.

This is one reason why I don't like Perl, though many people love it. A motto of Perl is "There's more than one way to do it", and as a result people have a huge amount of freedom to develop different idioms in coding. And so reading the code is like understanding english spoken in lots of different accents. It might add to the richness of life, but it does not aid speed of understanding. A language with more constraints, like C, Java or C#, still allows personal style and idioms, but it tends to be much easier for one Java programmer just to pick up and read another's code.

However, in any programming language it is possible to write code that is hard to read, if you don't concentrate on readability. Readability is a very subtle thing, and something which is more readable for me might be less for you. It's analogous to spoken language again. If I am drunk, and mumble in a slurred voice everyone will find it harder to understand. However, with a southern English accent, another southerner might find me easier to understand than someone from Glasgow, whereas for someone from Glasgow it would be the other way around. Similarly, some code is just harder to read than other code. However, it is also true my colleague Jason might find my code easier to understand than Joel's, whereas one of the Aardvarks might find Joel's easier - neither is necessarily better, it is just more familiar.

So when you right code, you should try and make it more readable for everyone, and especially readable for the intended audience, for example, those on your project. This is one reason why coding standards are a good idea - which brace style to use does not matter, as long as everyone uses the same. This is one thing which heps cause the "Not Invented Here" syndrome.

So, I should get back to Andrew's point about spreadsheets. A spreadsheet is confusing because it presents two views to the world in one user interface. It presents a view to the user, who wants to use it to calculate something, and the programmer who wants to change how it does that calculation. And it can be good or bad at either. Normally the "user" user interface gets improved before the "developer" user interface, but I've written spreadsheets which were great to develop, but lousy to use. Normally the model-view-controller pattern will be helpful here for separating the two, but you could also use Smartspread, which provides a much better development environment, in my opinion, than Excel. But then I did write it, with Jason, so I'm biased.

There's lots more I want to rant about readable code, and I want to give some examples, but that can wait for another time.