It's great that the OP thought to copiously comment the opaque conditional that led to the 'collision of features' that caused the key to disappear.
But that isn't really helping. He had to find the code to begin with, go down the debug trail from scratch to get to the point of reading the comment. He had special knowledge to help him; most of the rest of us would have taken longer.
Big code bases need a 'business requirements' document. If e.g. you wanted to rewrite the codebase, you could read the BR doc and know that if you accomplished all that, you'd be feature-compliant in your new implementation. That is, you weren't going to get any rash of calls from customers about their feature being broken or entirely missing.
You can pore over the codebase and get all that info without the BR doc. But like my son complains at his job, shepherding a million-line behemoth ten years forward, much of what he sees in the code is opaque, badly done (and thus hard to figure out what's the feature and what's accidental side effects) or obsolete (that customer special became irrelevant five years ago or whatever).
A business requirements doc can be reviewed by actual non-programmers and judgements made of what's still relevant. So revisiting the project (reimplementing, integrating a new feature into the rats nest without disturbing previous features) becomes if not easy, at least possible in a bounded timeframe.
You young folks will have lots of tools for this kind of thing, born of Agile processes I suppose. I suspect any such database of entries is woefully sparse, badly described or never referenced. Like most 'productivity tools', if they aren't part of somebody's job description they become orphans.
Don't know the ultimate solution. People are people, and diligent leaving of breadcrumbs is just another annoying thing to do. But somebody (maybe you?) will bless you for it down the line!
Note that I do not discourage comments. Comments in code can be very useful.
But they do not help you find the code responsible for a certain business requirement. Not unless that's what you put in the comment e.g. a BR reference.
I find code comments to be at their best, when they explain how the code works or is to be used or how it relates to something elsewhere. You know, comments about the code or other code. Relevant to understanding what you're about to read.
Comments that are essentially user stories disrupt the flow and don't help interpret the actual logic. Those comments belong elsewhere.
Sadly, it seems like often documentation is only an afterthought - and it's even worse when it becomes disconnected from the code and either lost, or misleading because referring to a different version. (And not all code is done by businesses.)
Sure, but there's always a 'business requirement' of some kind. Else why write the code? We can call it 'government requirement' or 'game requirement' if we need to.
But that isn't really helping. He had to find the code to begin with, go down the debug trail from scratch to get to the point of reading the comment. He had special knowledge to help him; most of the rest of us would have taken longer.
Big code bases need a 'business requirements' document. If e.g. you wanted to rewrite the codebase, you could read the BR doc and know that if you accomplished all that, you'd be feature-compliant in your new implementation. That is, you weren't going to get any rash of calls from customers about their feature being broken or entirely missing.
You can pore over the codebase and get all that info without the BR doc. But like my son complains at his job, shepherding a million-line behemoth ten years forward, much of what he sees in the code is opaque, badly done (and thus hard to figure out what's the feature and what's accidental side effects) or obsolete (that customer special became irrelevant five years ago or whatever).
A business requirements doc can be reviewed by actual non-programmers and judgements made of what's still relevant. So revisiting the project (reimplementing, integrating a new feature into the rats nest without disturbing previous features) becomes if not easy, at least possible in a bounded timeframe.
You young folks will have lots of tools for this kind of thing, born of Agile processes I suppose. I suspect any such database of entries is woefully sparse, badly described or never referenced. Like most 'productivity tools', if they aren't part of somebody's job description they become orphans.
Don't know the ultimate solution. People are people, and diligent leaving of breadcrumbs is just another annoying thing to do. But somebody (maybe you?) will bless you for it down the line!