5 ms·

IMO, I only use three tags: DREAM, FIXME, and HACKS. The whole point is to write less code and better establish when to revisit things. - DREAM tags let me foc

IMO, I only use three tags: DREAM, FIXME, and HACKS. The whole point is to write less code and better establish when to revisit things. - DREAM tags let me focus on getting things shipped and avoid over optimizing/generalizing things that won't provide immediate value. When working in a professional context, they are always accompanied by a ticket. This adds a nice binding for whoever comes next to pick up the task. - FIXME is also used to help maintain focus, but with the rule that no code ever gets merged with this tag still in place. For personal projects my branches tend to be quite large, so I'm comfortable accumulating some small number of these. - HACKS calls out unintuitive behavior: breaks in abstraction layers, worst-practices that have better implementations than best-practices, or anything that smells "clever". Everything else is just comments that future me/team can look back on and say "he must have been drunk when he wrote this, but thanks to these comments I can clearly understand the context and at least what was intended."

deleted 4y ago
[deleted]
cellularmitosis 4y ago
I've had good success using a system with two levels of severity: - // STOPSHIP: the presence of this string anywhere in the codebase causes a production build to fail. - // TODO: for everything else.
qiskit 4y ago
What about "// TODO !", "// TODO !!", and "// TODO !!!". Where the number of !s indicates the urgency - the more the urgent.
legorobot 4y ago
My one tweak would be that in projects in development, the hard rules are less applicable. Sometimes I've found hard-coding some things (e.g. FIXME items) are to make it into production when developing a prototype and testing (< 1.0.0). Once you're reaching 1.0.0, you know these can no longer be sliding through, and you can support all of this in CI.
epage 4y ago
Another reason for a system like yours is TODO is just another backlog but one that no one tracks and grows stale. I much prefer either - TODOs are resolved before merge (your FIXME) - TODOs are moved (not copied) to the team backlog (maintaining in both places just gets them out of sync) - TODOs are converted to documentation explaining the approach (e.g. HACKs)
- Bedon292 4y ago
  I may switch to using FIXME for my personal mid development comments. But I do like having the TODOs maintained with a ticket number in the backlog. Such that you can find the relevant code easily, but there is a ticket and its not forgotten. Especially when it relates to weird behavior in a specific section of code. It also lets people know that that section still needs work when they see it while working in the codebase. Maintain the meat of it in the actual ticket for sure. But `TODO: ABC-123 - brief description` shouldn't really get out of sync. At least hasn't so far for projects I have worked on.
- mr-wendel 4y ago
  This is absolutely my second system, and one often preferred over my ... um... preferred system :D. In other words, I have my personal bias, but this approach is far easier to scale with a team over time. I still tend to keep the "HACKS" thing though, simply because they localize the documentation right where you need to be aware of it.
- codethief 4y ago
  4th option: - Create ticket in team backlog and add ticket number to TODO comment (and have CI pipeline check that ticket number is valid)
  - epage 4y ago
    You need to check both that its valid and that its still open. Many times I've seen TODOs with issues in code where the issue was closed. Since nothing gates the Issues being closed, you've now broken CI by closing them. Say you do get past that hurdle, you've added friction to the process of managing the backlog because the code now needs to be updated when Issues are rejected. The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue.
Bedon292 4y ago
I like the idea of DREAM. I find that there are lots of things I would like to improve, but not worth it at this time. Or even maybe ever. But it doesn't feel 'standard' either. While I am sure a team could set up custom highlights and the like, but it has seemed better to just use the standard ones that get picked up by most tools. Is the use of HACKS just to highlight the importance of a comment? I tend to just stick those in a regular comment. Or if extra important NOTE at the beginning. For instance I refactored code the other day forgetting why it was the way it was, it didn't work, and then made a NOTE for it so I don't do it again.
- mr-wendel 4y ago
  The point is to avoid having to search these out. IMO you're playing a losing game if you find yourself doing this. For "DREAM" there is a ticket for proper tracking. For FIXME, code review prior to merge is sufficient. For HACKS, you really only need to care when you happen to be working in that space. And yes, HACKS is to highlight the importance of a comment. It also signals an intentional deviation and an opportunity for someone to offer a suggestion on how to improve things.
dimgl 4y ago
I love this. I'm going to try using this going forward. Edit: I just added this into my editor but it's not highlighted by default. I wonder if there's a way to highlight it.
- larsrc 4y ago
  TODO: Add highlighting by default. There, fixed it.
- DiggyJohnson 4y ago
  Well then that depends on the editor, but surely it’s possible in whatever you’re using.
- abdusco 4y ago
  Jetbrains supports it, and I'd bet there's an extension for it in VS Code
  - legorobot 4y ago
    There is -- anchors[1] :) [1]: https://marketplace.visualstudio.com/items?itemName=ExodiusStudios.comment-anchors https://marketplace.visualstudio.com/items?itemName=ExodiusS...
ironmagma 4y ago
What about a hack, that needs to be fixed, but in reality fixing it is only a dream?
- politician 4y ago
  That's the code in production.
politician 4y ago
For hacks, I use REVIEW to declare that this code is the way it is but an aspiring soul is welcome to submit a PR that replaces this code with a working version of the "right way to do it". It shifts the burden from the developer who made it work to the developer who would prefer it work some other way which allows the project to make progress.

deleted 4y ago

[deleted]

cellularmitosis 4y ago

I've had good success using a system with two levels of severity: - // STOPSHIP: the presence of this string anywhere in the codebase causes a production build to fail. - // TODO: for everything else.

qiskit 4y ago

What about "// TODO !", "// TODO !!", and "// TODO !!!". Where the number of !s indicates the urgency - the more the urgent.

legorobot 4y ago

My one tweak would be that in projects in development, the hard rules are less applicable. Sometimes I've found hard-coding some things (e.g. FIXME items) are to make it into production when developing a prototype and testing (< 1.0.0). Once you're reaching 1.0.0, you know these can no longer be sliding through, and you can support all of this in CI.

epage 4y ago

Another reason for a system like yours is TODO is just another backlog but one that no one tracks and grows stale. I much prefer either - TODOs are resolved before merge (your FIXME) - TODOs are moved (not copied) to the team backlog (maintaining in both places just gets them out of sync) - TODOs are converted to documentation explaining the approach (e.g. HACKs)

Bedon292 4y ago
I may switch to using FIXME for my personal mid development comments. But I do like having the TODOs maintained with a ticket number in the backlog. Such that you can find the relevant code easily, but there is a ticket and its not forgotten. Especially when it relates to weird behavior in a specific section of code. It also lets people know that that section still needs work when they see it while working in the codebase. Maintain the meat of it in the actual ticket for sure. But `TODO: ABC-123 - brief description` shouldn't really get out of sync. At least hasn't so far for projects I have worked on.
mr-wendel 4y ago
This is absolutely my second system, and one often preferred over my ... um... preferred system :D. In other words, I have my personal bias, but this approach is far easier to scale with a team over time. I still tend to keep the "HACKS" thing though, simply because they localize the documentation right where you need to be aware of it.
codethief 4y ago
4th option: - Create ticket in team backlog and add ticket number to TODO comment (and have CI pipeline check that ticket number is valid)
- epage 4y ago
  You need to check both that its valid and that its still open. Many times I've seen TODOs with issues in code where the issue was closed. Since nothing gates the Issues being closed, you've now broken CI by closing them. Say you do get past that hurdle, you've added friction to the process of managing the backlog because the code now needs to be updated when Issues are rejected. The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue.

Bedon292 4y ago

I like the idea of DREAM. I find that there are lots of things I would like to improve, but not worth it at this time. Or even maybe ever. But it doesn't feel 'standard' either. While I am sure a team could set up custom highlights and the like, but it has seemed better to just use the standard ones that get picked up by most tools. Is the use of HACKS just to highlight the importance of a comment? I tend to just stick those in a regular comment. Or if extra important NOTE at the beginning. For instance I refactored code the other day forgetting why it was the way it was, it didn't work, and then made a NOTE for it so I don't do it again.

mr-wendel 4y ago
The point is to avoid having to search these out. IMO you're playing a losing game if you find yourself doing this. For "DREAM" there is a ticket for proper tracking. For FIXME, code review prior to merge is sufficient. For HACKS, you really only need to care when you happen to be working in that space. And yes, HACKS is to highlight the importance of a comment. It also signals an intentional deviation and an opportunity for someone to offer a suggestion on how to improve things.

dimgl 4y ago

I love this. I'm going to try using this going forward. Edit: I just added this into my editor but it's not highlighted by default. I wonder if there's a way to highlight it.

larsrc 4y ago
TODO: Add highlighting by default. There, fixed it.
DiggyJohnson 4y ago
Well then that depends on the editor, but surely it’s possible in whatever you’re using.
abdusco 4y ago
Jetbrains supports it, and I'd bet there's an extension for it in VS Code
- legorobot 4y ago
  There is -- anchors[1] :) [1]: https://marketplace.visualstudio.com/items?itemName=ExodiusStudios.comment-anchors https://marketplace.visualstudio.com/items?itemName=ExodiusS...

ironmagma 4y ago

What about a hack, that needs to be fixed, but in reality fixing it is only a dream?

politician 4y ago
That's the code in production.

politician 4y ago

For hacks, I use REVIEW to declare that this code is the way it is but an aspiring soul is welcome to submit a PR that replaces this code with a working version of the "right way to do it". It shifts the burden from the developer who made it work to the developer who would prefer it work some other way which allows the project to make progress.