Hacker News Reader

Comment by dep_b | Hacker News Reader

Just today I announced a sweep through all of the TODO's and to either turn them into issues, stories or remove them. Biggest problem in Xcode is that it clogs up the warning list and the real warnings get swamped by them. But it's funny to see that Rust has less outstanding TODO's than our brand new 45KLoC project.

View on HN

TODOS are great documentation. They often reveal design decisions, suboptimal implementations and the thought process of the creator.

This information is often completely lost in issues that noone will ever look at again.

I also like to do TODO sweeps, but with a bias towards rewriting the into documentation or leaving them in if the are actionable.

Instead of TODO, I often add a NOTE instead now, e.g.:

   NOTE: Attempting to re-synchronize here would cause an infinite loop because...

This prefix distinguishes such info from normal comments, which exclusively pertain to the code-as-written.

Agreed but that's not quite what's being discussed here.

Notes are great but the context is to make a note about something that can be improved in the future (something actionable), hence it being a TODO.

Huh, if I add a TODO to typical code then it's something that ideally needs to be done there (e.g. "todo handle errors from invalid inputs" -- it'll work if you don't but... it's not ideal), or in LaTeX reports it's something that needs to be resolved still before shipping to the customer (e.g. "todo set \endDate variable"). Never is it a design decision or documenting my thought process. Why would that ever be labeled todo or, if you mean that todos indirectly convey that, why would having todos throughout the code as a means of conveying design decisions be "great documentation"?

"This information is often completely lost in issues" - of course, because an "issue" is "a vital or unsettled matter" and are not meant to be revisited once resolved. Writing design decisions or thought processes in issues seems equally weird to using TODOs to document that. They're kept around because it costs nothing and you might want to refer back to it for details on some past problem, but I've never heard of that being considered documentation.

The Rust graph is inaccurate since Rust uses FIXME instead of TODO. Almost all of the usage of "TODO" in rustc relates to the todo!() macro, usually to stub out parts of tests.

Yeah you get vastly different numbers if you grep for FIXME (instead of the hundred or so todo's):

    $ rg FIXME compiler | wc -l
    1036
    $ rg FIXME | wc -l
    18656

Can't you configure Xcode to filter out such warnings?

TODOs offer valuable insight but they may not warrant turning into issues or stories. Removing valuable information because it's cluttering seems like a shame. Better if you can filter it in such a way that it doesn't clutter

Quick idea: You could use a different wording that doesn't get recognized by Xcode but sticks out in a similar way. It would take some time to get used to it though.

I think it's actually my linter generating these warnings! But I do like them to be resolved so I consider them issues.

everybody wants todos resolved but chances are that if a decision is made to fix, make issues or nuke them, they'll just get nuked instead

> Just today I announced a sweep through all of the TODO's and to either turn them into issues, stories or remove them.

I think it makes sense to get rid of inline TODOs.

On new unshipped projects I've gone down the road many many times where it starts with a TODO comment above a chunk of code and then it turns into a few lines of context or a summary of my thoughts. Then comes linking to references, recapping my thought process on the "why", potentially writing a couple of versions of the code and keeping them commented out, or even having a chat with a friend over IRC and copy / pasting the conversation next to the code.

Now you open a file and suddenly it's your code mixed with a massive brain dump of notes, research and a ton of other things that have no business being in your code base and of course your intent is to remove all of that stuff once you get the well thought out implementation but eventually all of this stuff builds up. Then it happens across multiple files and eventually it becomes really hard to figure out what you need to do.

Putting all of that stuff into a kanban board has been a huge win for me. Now I just drop all of that contextual info into a "research" list and I pick things off that list when I'm ready to really do them.

A made a video about this process a while back at https://youtu.be/HHOkcCqsipE?t=77. It shows an example of the before and the after.

Sorry to break it to you but these TODOs are a measure of technical dept you've accrued by limiting dev work to issues and stories.

"How noone could have seen how we got hacked (then we checked Git and found a `TODO: Fix Authentication`)"

"Yes, but authentication won't make the boat go faster"

Reply on news.ycombinator.com