7 ms·

I use TODO in my code all the time as shorthand for: "This code is functional, but if you are going to do another iteration you may want to consider the followi

I use TODO in my code all the time as shorthand for: "This code is functional, but if you are going to do another iteration you may want to consider the following improvement or optimization." It's not at all meant to be to be like an item in a TODO list. Code would be a terrible place to keep that.

Fiaxhs 7y ago
Correct me if I'm wrong but I use "FIXME" for this intent. I keep TODO for stuff actually left to implement.
- kjs3 7y ago
  That seems like a good compromise. I've used LOOKAT to note places where I got things going but felt like there was a better way of doing things if I had more time.
- BurningFrog 7y ago
  To me, FIX implies that something is wrong, not that it works but could use improvement. I would like to have a tag for "here's something that works, but could be improved" though!
  - sombremesa 7y ago
    Pray tell, what line would you NOT put that tag on? That's like, all code...
    - hawkice 7y ago
      I think we all occasionally write code we like, but I also write code I don't like, but only the most vague idea on how to improve.
    - kadoban 7y ago
      TODO is for when you know something specific that can be improved and want to document it, not just generally that nothing is perfect.
    - BurningFrog 7y ago
      I don't want to brag about my skills, so I won't answer that.
      - davidlinc1 7y ago
        I similarly don't want to brag about my skills in pointing out areas of improvement in code that others might think is optimal, so I won't answer that.
    - saagarjha 7y ago
      I occasionally get to write code that is as good as I think it can be. That doesn’t mean it’s perfect, but I don’t know how to improve it.
    - cgag 7y ago
      Something I've seen Jonathan Blow do that I like is tag things // @Speed when doing a quick to type but slow to run kind of first pass. It seems nice to have tags for places to jump where the improvements are obvious, rather than hoping to just remember/spot them later.
  - Hurtak 7y ago
    Isn't that what NOTE is for? The code is fine for now, but here are some constrains/limitations/implementation details that you should know when you want to touch that par of the code.
- yoloClin 7y ago
  Is there a standard for valid flags? I recently recommended a client use `TODOSECURITY` for todos which had security implications until fixed - I discovered functionality which was implemented before authorisation had been developed, resulting in a codepath which was unintentionally reachable by standard users. Seemed weird to make up a codeword but I wasn't aware of any standard convention, and visually highlighting high impact issues (w/ the bonus of greppability) seemed like a sane approach in rapid development environments.
  - james_s_tayler 7y ago
    Open a ticket for that straight away and start working on it immediately. Or 3 years later. Whichever actually happens.
    - yoloClin 7y ago
      Yeah, that's probably true. I don't have any visibility over that particular projects ticketing system but I imagine it was never raised given it wasn't fixed until I noticed it.
  - sophiebits 7y ago
    I’d strongly recommend not landing code that has known security problems.
    - yoloClin 7y ago
      It was my job to look for security problems.
sedatk 7y ago
Then write a regular comment, why use TODO at all?
- berkut 7y ago
  So that it's grep-able?
  - catalogia 7y ago
    It's also nice to highlight TODO and FIXME in your text editor for added emphasis. I believe Vim even does this by default.
    - nkozyra 7y ago
      I think this is the primary benefit. Only so many times can you scroll past a nagging ide hint before you say "FINE, I guess I'll do it now!"
  - sedatk 7y ago
    Why would you grep in a scenario where a note is written because "[the]... code is functional, but if you are going to do another iteration you may want to consider the following improvement or optimization.". It's exactly meant for when you encounter it, it's not meant to be found externally.
    - TeMPOraL 7y ago
      Because it's trivial to add special highlighting to such notes in most editors and IDEs. Hell, a lot of them come with a configurable list of these comment keywords already built in.
    - alpaca128 7y ago
      Why would you intentionally leave out a TODO tag to make it harder to find? Lowering the barrier to see such comments increases the chances of people actually handling them. Having a highlighted TODO in the code makes it much more visible even if you don't use grep.
Fakira 7y ago
TODO, as the name implies, should be things that must be done. Anything aspirational could be left as a mere ordinary comment. Personally I hate TODOs and only see them as temporary things to act as placeholders for the correct code. At some point, I will go through all todos and clear them.
- kanox 7y ago
  > TODO, as the name implies, should be things that must be done. A lot of people use them for things that "could" be done.
  - cmyr 7y ago
    yep, TODO is for things like possible optimizations or improvements that are known, and FIXME is for things that are... functioning, but incorrect by some reasonable definition. (YMMV)
  - nosianu 7y ago
    Also, there are things that "must be done" only if the code is extended but it may be perfectly fine as it is at the current state. So I add a TODO when I see that there will probably be the need for refactoring in the intermediate future, but there is no need in the current code base. That is a TODO that is triggered (to become a "true TODO") when that code is touched again, but it remains (justifiably) inactive for now. The reason I use not just a comment is what others here already said, it gets highlighted by the IDE, and I have too many other "gray" comments that would not get read unless someone is looking at those sections specifically, so another regular comment would be easily overlooked. The suggestion for external tools or files is even worse: Pretty much nobody will check them when it's time for refactoring. It has to be inline. Sure, it can't become too much, but one such "triggerable TODO" comment for just a few modules is fine. When I write the code I can often already see options to make it more scalable or generalizable, but as it is currently being use the additional cost is not worth it, and if there never is future expansion the code actually is fine as it is. When I already know what needs to be done because my brain is fully 'inside' this code it would be a waste to throw that knowledge away, and regain all the contextual knowledge and ideas with a lot of work a year later. Those are the cases when I add such comments. They are not necessarily "TODO" level at that point, I use that tag only when additional conditions are met and I'm sure I want to avoid missing the comment. Occasionally, when I have some time over, I scan through my TODOs, there are about 2/1000 LoC. Most of them I leave alone because the condition for their realization has not been met yet, but sometimes I find one of them is worth doing at that point. If it was a general comment I would have no chance to find them that easily. If they were in an external tool or file they would deviate from the actual code more and more, since we do quite a bit of refactoring due to growth and changing needs. But if there's a highlighted TODO in a module you are refactoring it's impossible to miss, so it is easy to update or remove those if they become invalid, even more so than regular "gray" comments.
kanox 7y ago
> This code is functional, but if you are going to do another iteration you may want to consider the following improvement or optimization. I assign the same meaning to TODO or FIXME markers but a lot of people see this is as a measure of poor quality so instead I write regular comments of the form "this could be made better by doing X and Y".
- somehnguy 7y ago
  That may work but I find those comments tend to get lost over time. TODO/XXX/FIXME support are built into IntelliJ which makes stuff like that super easy to find. If some random dev looks and decides its low quality because of those words...well I don't care because its a silly metric to judge on.
  - TeMPOraL 7y ago
    And even if they aren't supported by default in your IDE/editor, they're perfect hooks for recursive grep. A simple grep -rn TODO * and you see a nice list of all of them, with files and lines.
  - delusional 7y ago
    Intellj also supports custom "patterns". "Intellj supports it" is a pretty meaningless argument anyway.
    - somehnguy 7y ago
      Yeah I know I could define custom patterns and all that...but why? "Intellj supports it" means it makes my and the people on my teams lives easier. Instead of deciding on some arbitrary other thing we just use what the tool defaults to. Hardly a meaningless argument.
  - kanox 7y ago
    > those comments tend to get lost over time That's fine, they don't need to be tracked. There are other systems for issues that need tracking.
ddyevf635372 7y ago
Use IMPROVEME instead of FIXME ;)
- dudus 7y ago
  TODO, FIXME and XXX are built into tools already. Sure you can make new stuff up but it makes it harder to find later.
  - ygra 7y ago
    Those things are configurable, though, so new markers are rarely problematic from a tooling perspective. Getting your teammates to agree on using the same markers is perhaps the bigger problem.
    - dudus 7y ago
      Making them agree is not necessarily the hardest. But remembering to tell new team members in a year or two. Or revisiting the codebase in 5 years from now. I doubt you'll remember
rkagerer 7y ago
For small projects without issue tracking, I use TODO for this iteration (or soonafter), and WISHLIST for "would be nice" future optimizations.
- Jach 7y ago
  Might I suggest you give a chance to having separate TODO and WISHLIST and TASKS text files in the root folder that use whatever id scheme you like and point to the code, with the code referring back to those ids only rarely? Or even a single file with sections for those things and more, perhaps called PLAN? Keeping things separate keeps the code tidier, gives you license to put more details than you're likely to put in a one or two line comment, lets you refer to multiple code points instead of the local comment area, can be given to a high school student temp worker, and so forth. For personal projects I've used https://github.com/dspinellis/git-issue https://github.com/dspinellis/git-issue a few times for a local command line issue tracker, it's not bad. I've got a longstanding mental TODO to try out Fossil one of these days though with all that and more integrated...
deleted 7y ago
[deleted]
mewse 7y ago
The lead programmer at my very first coding job taught me to put a string of at least three hash marks in a comment, to denote “this is a thing which is okay during development but absolutely must be changed/fixed before shipping this product”. The more essential the change/fix, the more hashes. Made it really easy to do a global search for them, and you could easily filter the results to only show the most important ones by searching for longer strings of hashes. Twenty years later and I’m still doing that in my personal projects.
- Jach 7y ago
  At my work we just file a bug and make sure it gets prioritized as a must-fix... The code might contain a bug number and remark too for redundancy, but the bug itself generally spells out the bits of code that need to be changed/removed/whatever. Using code comments really seems like the wrong place to prioritize changes. Even on personal projects.
  - girvo 7y ago
    I don't really want to use a bug tracking system on my personal projects, though, so I can see why someone would choose to do the TODO or hash idea
    - imtringued 7y ago
      If I don't write down everything I will forget what I am working on. Personal projects often get delayed by random things because they don't have a fixed schedule. After a while I forget what I am supposed to work on. What I do instead is I just write an issue with nothing more than a single sentence (often just a title with no body). If a new contributor wants to work on the project then they can use that issue as a starting point to join the project and ask for clarification how I want to it to be implemented. I personally wanted to contribute to a few projects but it was difficult to track what is currently being worked on or what needs to be done. When an opensource developer only works 8 hours a week on a project you don't want to waste their limited time by having a dozen people ask them what needs to be done and then not doing anything (because a feature might not be relevant to you but you couldn't have known that because it wasn't written down).
gwbas1c 7y ago
I think TODOs are fine for small projects, or early code. HOWEVER: For a mature project, TODOs should be found and reviewed during the pull request. Either they should be fixed prior to merge, or a ticket should be filed. (With a link placed in the TODO comment.) In the rare case that a TODO remains without a ticket, it really should be something obscure that really doesn't need to be fixed. For example, TODOs are great for micro-optimizations or suggestions for long-term refactoring.

Fiaxhs 7y ago

Correct me if I'm wrong but I use "FIXME" for this intent. I keep TODO for stuff actually left to implement.

kjs3 7y ago
That seems like a good compromise. I've used LOOKAT to note places where I got things going but felt like there was a better way of doing things if I had more time.
BurningFrog 7y ago
To me, FIX implies that something is wrong, not that it works but could use improvement. I would like to have a tag for "here's something that works, but could be improved" though!
- sombremesa 7y ago
  Pray tell, what line would you NOT put that tag on? That's like, all code...
  - hawkice 7y ago
    I think we all occasionally write code we like, but I also write code I don't like, but only the most vague idea on how to improve.
  - kadoban 7y ago
    TODO is for when you know something specific that can be improved and want to document it, not just generally that nothing is perfect.
  - BurningFrog 7y ago
    I don't want to brag about my skills, so I won't answer that.
    - davidlinc1 7y ago
      I similarly don't want to brag about my skills in pointing out areas of improvement in code that others might think is optimal, so I won't answer that.
  - saagarjha 7y ago
    I occasionally get to write code that is as good as I think it can be. That doesn’t mean it’s perfect, but I don’t know how to improve it.
  - cgag 7y ago
    Something I've seen Jonathan Blow do that I like is tag things // @Speed when doing a quick to type but slow to run kind of first pass. It seems nice to have tags for places to jump where the improvements are obvious, rather than hoping to just remember/spot them later.
- Hurtak 7y ago
  Isn't that what NOTE is for? The code is fine for now, but here are some constrains/limitations/implementation details that you should know when you want to touch that par of the code.
yoloClin 7y ago
Is there a standard for valid flags? I recently recommended a client use `TODOSECURITY` for todos which had security implications until fixed - I discovered functionality which was implemented before authorisation had been developed, resulting in a codepath which was unintentionally reachable by standard users. Seemed weird to make up a codeword but I wasn't aware of any standard convention, and visually highlighting high impact issues (w/ the bonus of greppability) seemed like a sane approach in rapid development environments.
- james_s_tayler 7y ago
  Open a ticket for that straight away and start working on it immediately. Or 3 years later. Whichever actually happens.
  - yoloClin 7y ago
    Yeah, that's probably true. I don't have any visibility over that particular projects ticketing system but I imagine it was never raised given it wasn't fixed until I noticed it.
- sophiebits 7y ago
  I’d strongly recommend not landing code that has known security problems.
  - yoloClin 7y ago
    It was my job to look for security problems.

sedatk 7y ago

Then write a regular comment, why use TODO at all?

berkut 7y ago
So that it's grep-able?
- catalogia 7y ago
  It's also nice to highlight TODO and FIXME in your text editor for added emphasis. I believe Vim even does this by default.
  - nkozyra 7y ago
    I think this is the primary benefit. Only so many times can you scroll past a nagging ide hint before you say "FINE, I guess I'll do it now!"
- sedatk 7y ago
  Why would you grep in a scenario where a note is written because "[the]... code is functional, but if you are going to do another iteration you may want to consider the following improvement or optimization.". It's exactly meant for when you encounter it, it's not meant to be found externally.
  - TeMPOraL 7y ago
    Because it's trivial to add special highlighting to such notes in most editors and IDEs. Hell, a lot of them come with a configurable list of these comment keywords already built in.
  - alpaca128 7y ago
    Why would you intentionally leave out a TODO tag to make it harder to find? Lowering the barrier to see such comments increases the chances of people actually handling them. Having a highlighted TODO in the code makes it much more visible even if you don't use grep.

Fakira 7y ago

TODO, as the name implies, should be things that must be done. Anything aspirational could be left as a mere ordinary comment. Personally I hate TODOs and only see them as temporary things to act as placeholders for the correct code. At some point, I will go through all todos and clear them.

kanox 7y ago
> TODO, as the name implies, should be things that must be done. A lot of people use them for things that "could" be done.
- cmyr 7y ago
  yep, TODO is for things like possible optimizations or improvements that are known, and FIXME is for things that are... functioning, but incorrect by some reasonable definition. (YMMV)
- nosianu 7y ago
  Also, there are things that "must be done" only if the code is extended but it may be perfectly fine as it is at the current state. So I add a TODO when I see that there will probably be the need for refactoring in the intermediate future, but there is no need in the current code base. That is a TODO that is triggered (to become a "true TODO") when that code is touched again, but it remains (justifiably) inactive for now. The reason I use not just a comment is what others here already said, it gets highlighted by the IDE, and I have too many other "gray" comments that would not get read unless someone is looking at those sections specifically, so another regular comment would be easily overlooked. The suggestion for external tools or files is even worse: Pretty much nobody will check them when it's time for refactoring. It has to be inline. Sure, it can't become too much, but one such "triggerable TODO" comment for just a few modules is fine. When I write the code I can often already see options to make it more scalable or generalizable, but as it is currently being use the additional cost is not worth it, and if there never is future expansion the code actually is fine as it is. When I already know what needs to be done because my brain is fully 'inside' this code it would be a waste to throw that knowledge away, and regain all the contextual knowledge and ideas with a lot of work a year later. Those are the cases when I add such comments. They are not necessarily "TODO" level at that point, I use that tag only when additional conditions are met and I'm sure I want to avoid missing the comment. Occasionally, when I have some time over, I scan through my TODOs, there are about 2/1000 LoC. Most of them I leave alone because the condition for their realization has not been met yet, but sometimes I find one of them is worth doing at that point. If it was a general comment I would have no chance to find them that easily. If they were in an external tool or file they would deviate from the actual code more and more, since we do quite a bit of refactoring due to growth and changing needs. But if there's a highlighted TODO in a module you are refactoring it's impossible to miss, so it is easy to update or remove those if they become invalid, even more so than regular "gray" comments.

kanox 7y ago

> This code is functional, but if you are going to do another iteration you may want to consider the following improvement or optimization. I assign the same meaning to TODO or FIXME markers but a lot of people see this is as a measure of poor quality so instead I write regular comments of the form "this could be made better by doing X and Y".

somehnguy 7y ago
That may work but I find those comments tend to get lost over time. TODO/XXX/FIXME support are built into IntelliJ which makes stuff like that super easy to find. If some random dev looks and decides its low quality because of those words...well I don't care because its a silly metric to judge on.
- TeMPOraL 7y ago
  And even if they aren't supported by default in your IDE/editor, they're perfect hooks for recursive grep. A simple grep -rn TODO * and you see a nice list of all of them, with files and lines.
- delusional 7y ago
  Intellj also supports custom "patterns". "Intellj supports it" is a pretty meaningless argument anyway.
  - somehnguy 7y ago
    Yeah I know I could define custom patterns and all that...but why? "Intellj supports it" means it makes my and the people on my teams lives easier. Instead of deciding on some arbitrary other thing we just use what the tool defaults to. Hardly a meaningless argument.
- kanox 7y ago
  > those comments tend to get lost over time That's fine, they don't need to be tracked. There are other systems for issues that need tracking.

ddyevf635372 7y ago

Use IMPROVEME instead of FIXME ;)

dudus 7y ago
TODO, FIXME and XXX are built into tools already. Sure you can make new stuff up but it makes it harder to find later.
- ygra 7y ago
  Those things are configurable, though, so new markers are rarely problematic from a tooling perspective. Getting your teammates to agree on using the same markers is perhaps the bigger problem.
  - dudus 7y ago
    Making them agree is not necessarily the hardest. But remembering to tell new team members in a year or two. Or revisiting the codebase in 5 years from now. I doubt you'll remember

rkagerer 7y ago

For small projects without issue tracking, I use TODO for this iteration (or soonafter), and WISHLIST for "would be nice" future optimizations.

Jach 7y ago
Might I suggest you give a chance to having separate TODO and WISHLIST and TASKS text files in the root folder that use whatever id scheme you like and point to the code, with the code referring back to those ids only rarely? Or even a single file with sections for those things and more, perhaps called PLAN? Keeping things separate keeps the code tidier, gives you license to put more details than you're likely to put in a one or two line comment, lets you refer to multiple code points instead of the local comment area, can be given to a high school student temp worker, and so forth. For personal projects I've used https://github.com/dspinellis/git-issue https://github.com/dspinellis/git-issue a few times for a local command line issue tracker, it's not bad. I've got a longstanding mental TODO to try out Fossil one of these days though with all that and more integrated...

deleted 7y ago

[deleted]

mewse 7y ago

The lead programmer at my very first coding job taught me to put a string of at least three hash marks in a comment, to denote “this is a thing which is okay during development but absolutely must be changed/fixed before shipping this product”. The more essential the change/fix, the more hashes. Made it really easy to do a global search for them, and you could easily filter the results to only show the most important ones by searching for longer strings of hashes. Twenty years later and I’m still doing that in my personal projects.

Jach 7y ago
At my work we just file a bug and make sure it gets prioritized as a must-fix... The code might contain a bug number and remark too for redundancy, but the bug itself generally spells out the bits of code that need to be changed/removed/whatever. Using code comments really seems like the wrong place to prioritize changes. Even on personal projects.
- girvo 7y ago
  I don't really want to use a bug tracking system on my personal projects, though, so I can see why someone would choose to do the TODO or hash idea
  - imtringued 7y ago
    If I don't write down everything I will forget what I am working on. Personal projects often get delayed by random things because they don't have a fixed schedule. After a while I forget what I am supposed to work on. What I do instead is I just write an issue with nothing more than a single sentence (often just a title with no body). If a new contributor wants to work on the project then they can use that issue as a starting point to join the project and ask for clarification how I want to it to be implemented. I personally wanted to contribute to a few projects but it was difficult to track what is currently being worked on or what needs to be done. When an opensource developer only works 8 hours a week on a project you don't want to waste their limited time by having a dozen people ask them what needs to be done and then not doing anything (because a feature might not be relevant to you but you couldn't have known that because it wasn't written down).

gwbas1c 7y ago

I think TODOs are fine for small projects, or early code. HOWEVER: For a mature project, TODOs should be found and reviewed during the pull request. Either they should be fixed prior to merge, or a ticket should be filed. (With a link placed in the TODO comment.) In the rare case that a TODO remains without a ticket, it really should be something obscure that really doesn't need to be fixed. For example, TODOs are great for micro-optimizations or suggestions for long-term refactoring.