Once in a while you come across a part of code needs to be fixed. You put in a comment saying something like ‘FIXME’ or ‘BROKEN’ or just another ‘TODO’. Sure you have no time, you need to ship. You don’t even know how much work it is to fix it or how many tests break after your modifications. A comment is safe and clear.
After a while the code around it changes. The software is shipped and used. The comment is long forgotten.
One day a customer calls and reports about an incident which sounds like a bug. After minutes or hours debugging and finally pinning the bug you rediscover a long lost information:
// FIXME: shouldn't we do this here?
So next time you find a code part which looks strange or seems to have a bug, create an issue and describe why you think it does not do what it should. And even better: write a test and fix it.
Information Hiding in Source Code Comments
Use comments for additional details, not as an issue tracker.
or something like:
//TODO: real locking
Thread.Sleep(5000);