Creating a positive coding legacy

Its a sad fact that for many developers your day to day work will involve dealing with legacy code and, invariably, this code sucks. It can be global variables, lack of documentation, code without test coverage or all of the above and more. We’ve probably all been angered by it, cursing the developers we inherited the code from. How then can you make sure that your coding legacy is a stable one and not a ticking timebomb?.

If we are to contemplate creating a stable legacy then its worth considering for a moment what it means to inherit a problematic codebase. There are a number of very professional approaches to handling an inherited codebase. Rowan Merewood presented his ideas on the subject recently at PHPBenelux (slides here). He has some solid ideas about dealing with the legacy of inherited code or poorly documented code. He also introduces the fact that all code we write is future legacy code in waiting. That being said, you need to start making sure your legacy will be a good one.

I was once told to comment my code like my coding peers were psychopaths with OCD-like interest in good code and bad anger management skills. This is a good starting point. Following a coding standard is probably one of the next things you should choose to adopt. Developers are often very adaptable people,adept in multiple languages, but we have a massive dislike for inconsistency. I recently spent almost an hour updating a 3rd party library to follow a strict camelcasing pattern in variable names, the lack of consistency made me feel uneasy. Because the code followed no formalised pattern it had become fractured, incosistent and harder to follow. A good example of a recognised standard is the Zend Framework Coding Standard for PHP. According to the documentation the standard helps to “…ensure that the code is high quality, has fewer bugs, and can be easily maintained”. It will also keep the developers than inherit your code happier. Legacy++.

The benefits of a coding standard do not stop there. Another powerful tool in the toolset for a PHP developer is PHP_CodeSniffer, a tool designed to detect violations of a defined set of coding standards. In the way it is possible to “validate” HTML against a specific Doctype Declaration it is also possible to validate the syntax of your PHP against a defined rulebase. The ability to enforce coding style may seem restrictive at first but the longer you follow this kind of regime the more it will become second nature. It will also become a massive tool within your bug detection routines.

Documentation of code, as i touched on before, is likely one of the greatest assets in making your code a positive legacy. It’s can also be directly linked to the adoption of a coding style. In the case of phpDocumentor a formalised set of parameters within your code comments are used to allow for the automatic generation of documentation for your project. We all know that good documentation makes developers happy so this is a great start. Most good IDE’s will use this documentation for “hints” as you code, this is invaluable also.

Hopefully, by following these few simple steps you can begin to see the ease by which you can make your coding legacy a better place. These tips are aimed very much at the more beginner programmer because i’m sure that no experienced programmer would ever not follow these principles (cough*). Of course this is only the start as I have not touched on either Unit Testing or Continuous Integration. However, I think we can all learn something by recognising ourselves as the creators of coding legacies. Oh, and be scared of people that inherit your code, if its bad and they’re mental, then you better sleep with one eye open.

* well, I try to most of the time :)

further reading: