Your code is like a home. If your home is messy, it changes how you feel in the space. If my home is messy I feel weirdly ineffective and sloppy. Tidying up makes me feel empowered and capable.

Don't leave mess alone. Tidy it up. A codebase you actively nurture will make you feel like change is easy. Its well worth the time investment.

On the other hand, if you spend all your time tidying and cleaning, you never get anything done.

There is such a thing as "too tidy", and while everyone disagrees on where the point is, companies tend to be very good at forcing that point through constrained resources.

I don’t think many projects are at much risk of that. Most professional code I’ve seen is a barely functional mess. There is such a thing as “too tidy”. But I can count the number of times I’ve seen it in my career on one hand.

I can not count the number of code review comments about missing periods at the end of comment lines on one hand. If you include comparably worthless comments, I can use the binary system and will still run out of hand...

Ah that’s fair. I have nothing but contempt for those sort of comments too. They feel like a sort of petty tyranny of small scale thinking. Good, clean software usually needs to go through a chaotic messy period to find its identity - and find what the core abstractions really are. Like, first get the big details wrong, then iterate until you get the big details right enough. Then focus on the medium details, then the small details. Then release. Doing that process out of order is at best a waste of time, and at worst a massive distraction. Our attention is our most precious commodity as programmers. Wasting it inappropriately is criminal.

If you want to move deck chairs around on the titanic, at least have the common decency not to drag the rest of us into your orbit of BS.

And the best way to manage your home is to separate the tasks into tidying, organising and cleaning. 3 separate and distinct actions. The same applies to code and projects.

Maybe I understand it wrong, but I can't agree with this analogy as is...

An organized home means to do things right away. If the laundry is done and dried, then I'll put them away (organize them) immediately. I don't wait for other things (eg. the dishwasher) that need to be tidied up. If I service my bicycle in one room and leave a mess, then I'll clean it up right away and don't necessarily include other rooms in that cleaning cycle. But on the other hand, if I spot some dust in one room, I'll just grab the hover and go through the whole flat.

Actions can be separate, and so can scope and effort.

I feel a house is best managed when effort and scope are low, so it is in my best interest to keep it that way. If my task becomes the action to tidy my home, then I know something went wrong.

> If you don’t fix it… and the code is working… what is the problem?

Because most of the time your hack only works by accident, or doesn't handle expected corner cases, or leaves out important use cases, or is a ticking time bomb.

If you’re regularly encountering or writing code that only works by accident or doesn’t handle important use cases, it isn’t the fault of a TODO. A TODO should document something that has been considered and would potentially be an improvement, but is not currently necessary. It isn’t supposed to be a flag that says “warning: I’m checking in broken code.” If the accompanying code is actually deficient, reject the PR.

> If you’re regularly encountering or writing code that only works by accident or doesn’t handle important use cases, it isn’t the fault of a TODO.

You're confusing a symptom with the root cause.

TODO items are symptoms of a problem, one which can and does often manifest in code that is brittle and only works by coincidence.

> A TODO should document something that has been considered and would potentially be an improvement, but is not currently necessary.

Not really. A TODO is just a comment someone decided to add because at the moment they spotted something that might require some work, but couldn't be bothered to track it as a work item. Just that, nothing more.

> It isn’t supposed to be a flag that says “warning: I’m checking in broken code.” I

Except it actually is supposed to be a flag that states "yeah I know this is broken code but trust me I'll get around to really fix it at some time between not now and never"

I've lost count of the age-old TODO items I stumble upon on projects I've worked on that served no purpose other than either stating "I think this needs fixing but I can't be bothered to track work items in a ticket" or "I just need my PR to go through, trust me bro I'll do this right once I remember to fix my shit"

This is definitely not the way teams I have been on have used TODOs. It better not actually be broken code. It means “this works but I have an improvement in mind that doesn’t need to be done now.” There is no way I or anyone on my team is getting away with TODOing code that is literally broken.

I’m now legitimately frightened about what some people are apparently labeling TODO. If that’s the way you use it, no wonder you’ve come to the conclusion it’s terrible.

JetBrains IDEs actually highlight two different types of comments:

  // TODO
  // FIXME

I think it's nice to have the distinction, with the former being a general suggestion, whereas the latter is perhaps more urgent.

Not that people's opinions won't differ greatly anyways. Some might set up their static code analysis to complain about every single TODO item and actively manage them with their issue tracking system, others just won't care.

"born in a house with the television always on"

That's a Talking Heads lyric and not a point of fact.

> If you don’t fix it… and the code is working… what is the problem?

Two obvious problems: (1) more likely future bugs; (2) wasted time

Often "fix it later" means "de-duplicate this copy and pasted code later", where the copy is slightly different so there's some refactoring required to do that.

The future bugs come from changing one copy but forgetting to change the other. Sounds unlikely but very common in practice.

The wasted time comes from having to redundantly update both (or several!) copies. That's more work than it sounds because you have to understand the subtle differences in each, whereas if you had refactored them into one code base then the differences would be some obvious function/class/etc. Of course, each time, this update to all the copies is less effort than doing the refactoring, so the wasted time builds up gradually over time.

> If you don’t fix it… and the code is working… what is the problem?

It may be very inefficient, for example. Works now, but may unintuitively slow down when dealing with workloads that looked very far-fetched at the time.

I have inherited a really nice C++ codebase from 1980s that contains warnings for Year 2038 problem and all sorts of other potential issues, and I can't thank those engineers enough. So many times I've dug into a problem or started implementing a new feature only to discover that someone had already thought of that and left useful pointers in comments.

Whatever version control or note-taking applications they might've used instead, I doubt I could even run or open their files 30+ years later.

Sounds like there's no problem with //TODO: Fix later then if it's actively helping you.