Software Complexity vs. Complex Software

Over the years I have been hearing ‘this piece of the software is very complex’ ‘we cannot fix this easily, it is very complex’ etc. Most of the times when we hear this, we are either in a Sprint or a critical bug fix cycle. Both of these scenarios are time critical. So there is a decision to be made. Soon. And most of the times, the decision made is to ‘hot fix’ the piece with minimal time spent.

I believe many of us have been in that scenario. The ‘hot fix’ works. Customer is happy, the software in whole works. And Engineers close the issue.

But is the issue really closed? Who remembers what hot fix was done? How that hot fix was 'applied' to the code. Was it a quality fix? Did it fix the symptom or did it actually fix the cause?

All this boils down to one thing - Software complexity. Not Complex Software.

And the above process, in many cases, just increased the software complexity. If nothing was documented about how the fix worked, it adds to the complexity of the software 6 months from now. 12 months from now, the same engineer would find the same piece of code as complex (as there were probably other ad-hoc fixes/patches on top of this patch). They would not recall why this line was added:

var someValue = someOtherValue *0.65;

//100 lines of code

var someValueNow = someValue*0.5 > 1 ? someOtherValue : someValue * 0.25; //hotfix v1 <— this line was added for hotfix

What happened here is, some logic, got translated as is in the code, but not documented. No one understood what was the reason behind this logic. No one looked at the quality of the fix, whether good coding standards were followed (extract the logic into a function, keep functions specific to what they do) or not?

This, over time, increases the complexity of the code. Not that the software is complex. Complex software is what lands a rover on Mars. That is complex. Most of the times, a well written, documented software is NOT complex. It has gone higher in complexity, because of lack of standard coding practices (using software design principles), lack of documentation.

And there comes a day, when software owners are scared to make a change in the code. Why? Because, software has now become complex. Well, if the owners know how the code works (via documentation, or well constructed code), a change is never feared.

Some simple guidelines on things engineers can do to keep the complexity of the software to a manageable degree:

Design before coding - Often we see code that was rushed in (due to time constraints, due to lack of overall codebase knowledge etc...). These types of changes, while they do achieve 'something', many a times they are doing things that are either duplicated or not needed at all. This is what I call lint code. Well it is a little better than lint code - it executes, but only 20-30% of this code is really what was needed. Rest is just overhead lint. Things that could have been avoided if designed carefully.
Document what is needed - How much to document? If you are OK documenting a small reference to a issue number etc in teh code, do it. Someone later on can refer to the issue number (hopefully which has some explanation on how this issue was patched). Where to document? Something that is searchable. If the 'feature' being documented is more than just a bug fix, it should have its own page of documentation. If the change is a couple of lines of change, a small explanation in the bug tacker should suffice to make sure future owners know the why and how of the fix.
Test / Simulate - As much as engineers like creating software, we should like simulating the software BEFORE it goes to testing / quality assurance. Why? Because knowing how the piece of logic you wrote will work under different scenarios will help you make it more resilient. Bulletproof. Also, this gives you a ready platform to simulate a scenario, IF a bug is found later on.
In conclusion, its the owners of the code, over time, that make the complexity of the software higher or lower, without the actual product being complex or not.