This month’s invitation from Tom Zika asks us to consider production code and consider what quality makes the code ‘production grade’.
It’s interesting to think about all of the areas we may want to consider before putting some code into production – has it been reviewed, has it gone through sufficient testing, does it perform well compared to the existing code, are there any potential impacts downstream resulting from any changes, has documentation been updated accordingly, etc. – the list goes on.
However one key thing which I’d always advocate for when considering code to be production ready would be:
Readability
Code is rarely static. Like most technology it tends to age like fine… well, cheese. We inevitably rework solutions, configurations, environments, etc. over time, and its only a matter of time before we revisit some code after its entered production.
When this time comes it can be valuable to have code which is clearly readable as it can remove a lot of the headaches which come with maintaining code which someone else wrote, years ago, in their shed, after a heavy evening the night before.
The challenge should come from building the solution rather than deciphering the problem.
When writing new code I find its typically more effective to start off with simpler statements or constructs to flesh out the code with a focus on what we’re trying to achieve. Refactoring, fine tuning and performance review can then follow up at a later point, coming secondary to the clarity in the code.
By building the code up in this way the it can help keep the majority of the logic in a more simple and digestible format. There will be less surface area covered with more complex or obscure logic. Solving very particular challenges with this logic in code which can be seen as the exception.
It tends to be much easier to performance tune well written code than it is to unwrap and modify high performance spaghetti.
Below are some notes on areas which I’d look for under the banner of readability for production code:
- Clearly laid out – be consistent with indenting, formatting, line breaks and spacing, and generally adhere to the relevant best practices for the language or business which you’re working in.
- Relevant annotations – it’s at least useful to have a header to your script, procedure, class, etc. which describes its purposes and particularly anywhere to help follow program flow such as the closing of a lengthy
IFblock for example. - Keep it simple – as above, try to build the code up from the basics with an eye on what the result needs to be in a clear and simple way. Once the bare-bones are there then it might be time to build on that and add complexities and enhancements.
- Describe the oddities – for those requirement which need a bit of elaborate coding in there. You want to know what it does, why it’s there, and why it looks like the spaghetti it does. This is where you get liberal with use of comments.
- Sample data – in the case of a SQL script for example, maybe some indications of where it gets called from, or some example procedure calls to help illustrate the usage.
Having code which is presented in a way which clearly defines what it’s doing and why can help anyone who may need to come and support it at a later point, be that you or another member of your team.
There’s a lot of effort which can go into making code ‘production grade’ with potentially a lot of hoops to jump through to hit that bar. For me however it comes down to readability as the key.
The code will need to be revisited in the future, whether it be to build on the features or to fix a bug which has been found. It’s not always a great experience picking up some old code which has been lying around so I’d advocate doing your future self (and team) a favour and try to keep it as clear and readable as you can.
Essentially it’s about removing the friction when picking up code again after a length of time. It helps make our jobs that little easier, and that’s certainly a good thing.
Thank you to Tom for hosting this month and I look forward to reading some of the responses from around the community!
Andy Brownsword 