How many times have you come back to look at some code you wrote months or even years ago, and you have to spend significant time reminding yourself how it works? I can honestly say that’s happened to me a number of times. And the thing is that if its taken me time to try to understand my own code when I’m at least a little familiar with it, how much more time would it take for someone who is not familiar with it? Extending this, how much time do you spend on average per week trying to understand someone else’s code? Its probably more than you realise, can be significant, and which if reduced can increase your productivity.
As developers, we’re typically viewing existing code for one of two key reasons: Either we want to extend the piece of code to also support some additional scenario or data, rather than creating duplicate code elsewhere, or we’re trying to locate the cause of a bug in order to fix it.
Either way, what we’re focussed on is understanding how this piece of code is used by other parts of the application, whether just on one physical system or as part of a distributed network (e.g. consumers of a web accessible service.
This includes being able to identify:
- All the possible end to end usage (success and failure) scenarios the code plays a part in,
- What data is flowing in and out of the piece of code for each scenario
- Which scenarios the code has been written to handle and which (if any) it does not.
Making code easy to understand requires the author to put themselves in the shoes of someone trying to learn the above for the first time. How obvious is it from the code to gain the understanding that is required? And from experience, as a viewer of other peoples’ code I want to stay at the level of understanding how this code contributes to or handles specific usage scenarios. I don’t want to delve down into the detail of individual statements until I’ve grasped that higher level view. So keeping code understandable at a glance is key to keeping a viewer at that level. The following five techniques are some examples that I’ve used to help achieve this.
Code structure logically related paths of code
For example if two or more conditional paths of the code require the same processing, then group these such that its easy to spot what’s happening. Its harder to understand what is performed for a given usage scenario if the conditional logic is split across two or more if statements or blocks of code.
Keep conditional statements short and natural
If statements that have three or more conditions are difficult to start to understand all the possible scenarios and the outcome quickly. Typically limit conditions to two or one, or provide a comment that makes it clear what’s happening.
Also, avoid double negatives for example ‘if not no_data_read’ as psychologically, its harder for a viewer to read and understand.
Use longhand and sacrifice small performance gains
Shorthand logic requires a viewer to have to stop and consider the specifics of the statement logic and lose the sight of the wider ‘what processing is being performed for this scenario’. So, avoid code shorthand where possible, for example shorthand ifs and shorthand processing statements unless these are well commented, so that a viewer can more easily see what processing is being performed.
Document anything that is potentially not obvious
Add code level comments for edge case scenarios, or conditional statements for which the need might not be immediately obvious to someone viewing the code. A good comment that provides a system or business level reason (for example ‘Only send 1000 records at a time so this doesn’t exceed single queue message size’) helps any viewer of the code stay at the scenario level.
Clearly define the purpose and use of a function and class of code
Using function header and class level comments, describe in detail what this class and function provides, how its intended to be used, how its not intended to be used (if there are some scenarios that you are aware of as a code author), what data goes in (including examples if it could vary or its not obvious) and what is returned (again, including examples). Providing this type of documentation is extremely helpful to give viewers of your code that higher level understanding.
The above are suggestions to start getting you thinking about what helps you and others understand each other’s code better and faster. Its holiday season time, so why not start implementing some maintainable code practices of your own and give yourself and others the gift of a little extra time.
I’d love to hear what suggestions you have for making code easy to understand and maintable. Contact Us and tell us about what works for you or what challenges you are experiencing right now.