[I wrote this approximately 2007. I originally had this as one of my thoughts about tech on my main harrywood.co.uk ‘tech’ section. Now demoting it to the blog archive]

The key to creating maintainable software, is to write clear code, with comments and meaningful variable names. Not exactly the most earth shattering statement I know. But here’s a couple of interesting things I’ve noticed…

Ask any programmer if they write comments and choose meaningful variables names, they will nod earnestly, and agree wholeheartedly that this is important. But if all programmers are so good at creating maintainable code, where is all this unmaintainable code coming from? The problem is, it’s like asking a guy if he is a good driver. 90% of motorists consider themselves to be above average driving ability. The truth is many programmers see code maintainability (commenting etc) as a secondary task, to be addressed after creating the code, if they have time, rather than seeing it as a basic inbuilt part of the coding process. As for me, I always write maintainable code. You can trust me on this, because I can’t drive 🙂

Another big problem is project managers. They all read their project management books which say that a well run I.T. project has ‘technical documentation’ as one of the final deliverables. This becomes a priority, usually after the coding is done (we all know it should start as design documents written beforehand), but some project managers fail to realise the following. The purpose of delivering technical documentation is to make the system more maintainable, helping future developers. But under the umbrella of system maintainability, you really must start with basic code maintainability. If you pester your developers to jump through the document hoop, you may be asking them to describe spaghetti, which is difficult and time-consuming. If you ask them to ensure the code is maintainable first (conduct peer reviews), the result is code which the developers feel confident with, perhaps even proud of, and the documentation process becomes much less of a chore. But more importantly… You can deliver all the documentation you like, but if the code is spaghetti, any future developers are completely screwed!

It’s not just about future developers though. If code is not maintainable, then the programmers themselves will not understand their own spaghetti after a while. It only takes a week or so to build an unmanageable heap of spaghetti code. After that, any new features being heaped on top, will take longer and longer to develop, and will be more and more buggy. The same symptoms arise if a constant stream of change requests leads to a bad architectural structure. Either way, for any complex project, it is essential that code is kept tidy and well commented, and as I explained before, many programmers do not do this. If a manager doesn’t want to get their fingers dirty checking the code, they they should put a peer review process in place i.e. ask the developers to check each other’s code.