Hacker News new | past | comments | ask | show | jobs | submit login

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.




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: