Here's a simple solution: change your comments (and your mindset) from vague "will fix it later" to a more specific "fix once <trigger condition> occurs". Ideally trigger condition is tied to automated alerts & metrics, but that's not strictly necessary.
You'll realize that most of the time trigger condition will not occur in the foreseeable future, or you don't even know what trigger condition is. Latter usually means you're planning to optimize because you want to, not because there's any business value in it. Stop thinking that it needs fixing because there's room for fixing. Businesses are all about tradeoffs, not perfectionism.
E.g. instead of "optimize this query in the future" write "optimize this query when we have customers with 1000+ orders", or "optimize this query when response time goes above 500ms", or even "optimize this query when N+ customers complain".
One other thing which I find very useful is to write tests which will start failing once the <trigger condition> changes. For example if today the database version I'm testing against disallows some query shape I can:
- write a test that verifies the failure
- add a todo comment in code linking to the test to fix the code when test fails
Then eventually the test will start failing, you can fix the code and the test and profit.
Good point. But that works only if the version number is the thing you want to test. And also it's possible that newer versions include the bug or some even newer version introduces a regression re-introducing the bug.
I'm a believer of user-facing testing - i.e. test things like how a user would operate them. So in the context of building a federated query engine our users won't care what version of Postgres they are connecting to - they will care however that the query they wrote doesn't work - doesn't matter what Postgres version.
I’ve tried this, fails in the discovery aspect imho. By the time the trigger condition occurs no one’s checking that comment that’s buried god knows where. You’re at most going to see it when something’s already broken and you’re investigating the causes.
Using jira cards with “depends on” relations work better if you already have one for the trigger condition, but even for that if it’s months or years away there’s a big chance that the trigger condition is done in a new duplicate card because no one remembers the old one.
What I usually do whenever I add TODOs and FIXMEs is create a corresponding issue with a short context description of why this came to be this way, what are the potential limits to the current code, and how I think it could be addressed, with permalink (or permalinks) to the line(s) in the repo, and add a specific label (or JIRA epic).
This way it allows to easily search and find all code entries corresponding to a specific case, quickly jump back in without too much reverse engineering someday in the future (by myself or someone else), and monitor debt growth by zooming in on the label with a search (or just looking at the epic).
"By the time the trigger condition occurs no one’s checking that comment that’s buried god knows where. "
You can make the trigger condition actual code and have it send you an email for example, or log to somewhere where you do check (depending on the project).
That’s better, but many trigger conditions are abstract and not implementable as alerts.
Consider for example “this code will only work under the assumption that all of our clients are US companies”.
Detecting in code that the company is aiming at international expansion soon is probably not possible, because if your code was generic enough to account for different countries you wouldn’t have this problem in the first place.
If you can tie these to automated alerts that's great. But there's no need to automate everything, "Do things that don't scale".
I make these comments searchable (they always start with "# TODO: "). And then once a month (or when you're bored) you can go through these and reevaluate them.
Yes, it's a non-scaleable manual process. And I absolutely don't care because it takes less than 30 minutes each month. No amount of effort invested in automation will ever pay off, so I'm pretty happy to do it manually.
I would love these TODO comments to automatically create issues in Github so that we could also discuss these, but unfortunately all of the Github Actions I've tried fail miserably when lines are moved or comments are edited.
"Detecting in code that the company is aiming at international expansion soon is probably not possible"
It is somewhat, if you also keep some general variables for this like "US_Only" that you have to keep track of, but yes, there are of course limitations with that approach. If you do it wrong, it gives just false security that blows up at the wrong time.
That's extra effort too, might as well fix it on the spot.
Also you might not have the data to trigger it in first place. If your todo is "optimize caching of this data" it's hard to see overall system hitratio to know when it might be worth it to start optimizing.
There are also dependency todos, "new version of the thing has that feature and this needs to be changed once we upgrade to it"
"That's extra effort too, might as well fix it on the spot."
It depends on the problem. Some things you do not just "fix on the spot", they take longer and sometimes you do have other, more urgent problems. Those are times, when I do something like this.
Occasionally I have had luck by embedding assertions in C code that fail when the trigger conditions are met… but mostly that’s not practical. I’ve never had any luck with the dependent ticket approach, those tickets always end up lost forever.
I experienced similar things, but not at work, but in life, about trivial things. I often told myself I would do it sometime after, but never. And then, I point a certain specific time to do it, I almost always do it. So I think if you set a exact time point, the probability will get higher.
You'll realize that most of the time trigger condition will not occur in the foreseeable future, or you don't even know what trigger condition is. Latter usually means you're planning to optimize because you want to, not because there's any business value in it. Stop thinking that it needs fixing because there's room for fixing. Businesses are all about tradeoffs, not perfectionism.
E.g. instead of "optimize this query in the future" write "optimize this query when we have customers with 1000+ orders", or "optimize this query when response time goes above 500ms", or even "optimize this query when N+ customers complain".