Standardisation and code

This article is about standardisation, particularly how it relates to understanding code.  I’ll first go into an historical example that highlights the lack of standardisation in an area where we take it for granted today.  After that I’ll get into code, and how understanding code is like understanding data via visualisations.  In both the historic case and modern code reading, standardisation has benefits that might not be immediately obvious.

Historical guns

This photo shows my friends Ted and Ant shooting calivers at Kentwell Hall.  A caliver was an innovation in its day, because it was an arquebus (long gun) with a standard bore or inner diameter to its barrel.

The standard bore was important.  Before this, each gun might be made to a slightly different size.  This meant that each would need slightly different-sized lead balls as ammunition.  The ball needs to be a snug fit in the barrel – if it’s too small then the force of the exploding gunpowder behind it escapes around the sides of the ball rather than pushing the ball forwards.  If it’s too big then it won’t fit down the barrel.

Non-standardised barrels meant that the gunsmith would need to sell you the gun plus a mould for the balls that fit the gun.  The consequence of this was that it was hard to equip an army – you couldn’t have a single stock of balls that could be distributed to whoever needed them.  Calivers and other guns with standardised bores simplified supply.

Why bother?

I think it’s useful to take a quick detour into visualising data.  When I’m doing something like a bar chart or an architecture diagram, I think that similarity and difference should be meaningful:

• If two things are similar, they should look similar
• If two things are different, they should look obviously different

That means the colour, shape and position of things matter, even though they might seem trivial.  Things that are the same in some way, e.g. plug-ins as opposed to core code, should share some property in common – the same shape, colour or position. This means getting their position pixel perfect, the shade just so, or whatever else you need to make them the same rather than similar.

Getting back to code, does it have methods called ReadX (e.g. ReadAccount), GetX or FetchX? Or maybe some combination of these three… Are the tables in your database called Account or Accounts?  (Are the names plural or singular?) I’m not arguing for or against of these, but I am arguing for consistency.

Programmers are used to thinking of code as the important thing.  However, it’s a visualisation or expression of intent (which you might also call requirements, design etc.).  Despite being executed by a computer, it’s also a tool for human – human communication, to convey the meaning behind the code.  This communication is clearer if similarity and difference in the expression reflects similarity and difference in the underlying intent.  So, all methods to read data should be called Read…, Get… or Fetch… consistently.  Pluralisation and capitalisation should be consistent etc.

This isn’t an exercise in a senior member of a team dictating their personal preferences on the rest of the team.  Like all shared ways of working, it works best if the team owns the decision-making.

While speed, scalability etc. matter, so do correctness, ease of change, ease of having many people work on the code and so on. Professional programming is actually a social activity that happens to involve computers, so things like removing friction in how people understand each other are often worth it.