6 ms·

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 du

by 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).
- shhsshs 7y ago
  I agree in principal, though if the intent is to have the minimal amount of side-tracking while marking something as TODO for the future, I don’t think you can get better than a comment. A nice cli interface for creating tickets in GitHub/Jira/etc. would help with that. I wonder, would it be nice to have a pre-commit hook that scans for TODO comments, removes them, and drafts tickets? Then both flows would work well.
  - Jach 7y ago
    I suppose it depends on how far you trust your ability to keep everything in your head, and reload everything coming back, and follow through on notes to self. I make todos too, but I try to honor a self-agreement that they be short lived and ideally not make it very far beyond my machine. I linked https://github.com/dspinellis/git-issue https://github.com/dspinellis/git-issue in another comment but it gives a sense of the command line experience. I've also at times hacked up various scripts to create or modify items in github/jira/our internal POS, it can make things more likely to hit the tracker than to be met with a shrug. (It's so odd how sensitive programmers can be to even minor blocks in flow like a few seconds waiting for a webpage, or avoiding refactoring a method / class because in Java a new method might best belong to a new class which to do things 'proper' often entails a new file and then another new file for unit tests, adding them to version control, and all that takes like 30 seconds even with IDE support and is annoying.) I've at times thought about a small vim command that would call one of those scripts to create a new issue pre-templated with the file and location I was on, create, then insert the work item id, but never got around to it. As a pre-commit hook something to look for TODOs explicitly might be interesting, though I generally dislike hooks.
  - gumulka 7y ago
    I have somethink like this in the pre-commit script: https://pastebin.com/XmMHTvZR https://pastebin.com/XmMHTvZR It works only for gitlab and assumes that the remote is named origin. This will create an issue with the title text being everything after TODO. It does not support multiline and only looks at the newly added lines, but does not remove from the commit or alters them.
- dragonwriter 7y ago
  > Using code comments really seems like the wrong place to prioritize changes. It's a poor place for long-term tracking, but it's a great place for recording notes while minimizing context-switching cost while coding.
rurban 7y ago
This should be marked as FIXME, not some management savy ###
- hutzlibu 7y ago
  Why? I also use ###. It is just a different style.
- coldtea 7y ago
  Neither FIXME nor ### are "standards" so the distinction is moot. Can use either...
mytailorisrich 7y ago
> “this is a thing which is okay during development but absolutely must be changed/fixed before shipping this product”. These should not reach the master codebase and should thus be fixed before you merge your code into it.
- alkonaut 7y ago
  I think if multiple people are working on a code base which will not ship for years, then having those can be acceptable. Obviously if “next release” is a deploy from master in 2 weeks then it isn’t.
  - mytailorisrich 7y ago
    It does not make it acceptable, quite the opposite as there would actually be less time pressure to ship code. What you describe would lead to an accumulation of issues over time that will degrade the codebase until it ships and then makes maintenance a nightmare.
    - alkonaut 7y ago
      A code base that will ship in 2 years will be shipping for various non-production reasons until then. There will be stakeholder demonstrations and alpha releases and things where the code must be functional (runnable), but it may not be production ready in terms of completeness, security etc. The "accumulation of issues" is there regardless. Leaving TODO's isn't cutting corners or accumulating technical debt. It's simply something that is still to do. Any project will have an issue management system with outstanding issues, but a note in the code is worth more than a thousand words in an issue. "TODO: here is where the validation of parameters must be done, see issue #123". or "TODO: enable right-to-left in these two textboxes when right-to-left text input is added, see issue #234". There is no value in keeping a main branch "clean" from TODO comments because it's somehow more hygienic. The code needs to be runnable at all times, even with incomplete features. Reaching zero TODO's before a product ships is a matter of grepping for the strings.
      - 7y ago

by mewse 7y ago

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).
shhsshs 7y ago
I agree in principal, though if the intent is to have the minimal amount of side-tracking while marking something as TODO for the future, I don’t think you can get better than a comment. A nice cli interface for creating tickets in GitHub/Jira/etc. would help with that. I wonder, would it be nice to have a pre-commit hook that scans for TODO comments, removes them, and drafts tickets? Then both flows would work well.
- Jach 7y ago
  I suppose it depends on how far you trust your ability to keep everything in your head, and reload everything coming back, and follow through on notes to self. I make todos too, but I try to honor a self-agreement that they be short lived and ideally not make it very far beyond my machine. I linked https://github.com/dspinellis/git-issue https://github.com/dspinellis/git-issue in another comment but it gives a sense of the command line experience. I've also at times hacked up various scripts to create or modify items in github/jira/our internal POS, it can make things more likely to hit the tracker than to be met with a shrug. (It's so odd how sensitive programmers can be to even minor blocks in flow like a few seconds waiting for a webpage, or avoiding refactoring a method / class because in Java a new method might best belong to a new class which to do things 'proper' often entails a new file and then another new file for unit tests, adding them to version control, and all that takes like 30 seconds even with IDE support and is annoying.) I've at times thought about a small vim command that would call one of those scripts to create a new issue pre-templated with the file and location I was on, create, then insert the work item id, but never got around to it. As a pre-commit hook something to look for TODOs explicitly might be interesting, though I generally dislike hooks.
- gumulka 7y ago
  I have somethink like this in the pre-commit script: https://pastebin.com/XmMHTvZR https://pastebin.com/XmMHTvZR It works only for gitlab and assumes that the remote is named origin. This will create an issue with the title text being everything after TODO. It does not support multiline and only looks at the newly added lines, but does not remove from the commit or alters them.
dragonwriter 7y ago
> Using code comments really seems like the wrong place to prioritize changes. It's a poor place for long-term tracking, but it's a great place for recording notes while minimizing context-switching cost while coding.

rurban 7y ago

This should be marked as FIXME, not some management savy ###

hutzlibu 7y ago
Why? I also use ###. It is just a different style.
coldtea 7y ago
Neither FIXME nor ### are "standards" so the distinction is moot. Can use either...

mytailorisrich 7y ago

> “this is a thing which is okay during development but absolutely must be changed/fixed before shipping this product”. These should not reach the master codebase and should thus be fixed before you merge your code into it.

alkonaut 7y ago
I think if multiple people are working on a code base which will not ship for years, then having those can be acceptable. Obviously if “next release” is a deploy from master in 2 weeks then it isn’t.
- mytailorisrich 7y ago
  It does not make it acceptable, quite the opposite as there would actually be less time pressure to ship code. What you describe would lead to an accumulation of issues over time that will degrade the codebase until it ships and then makes maintenance a nightmare.
  - alkonaut 7y ago
    A code base that will ship in 2 years will be shipping for various non-production reasons until then. There will be stakeholder demonstrations and alpha releases and things where the code must be functional (runnable), but it may not be production ready in terms of completeness, security etc. The "accumulation of issues" is there regardless. Leaving TODO's isn't cutting corners or accumulating technical debt. It's simply something that is still to do. Any project will have an issue management system with outstanding issues, but a note in the code is worth more than a thousand words in an issue. "TODO: here is where the validation of parameters must be done, see issue #123". or "TODO: enable right-to-left in these two textboxes when right-to-left text input is added, see issue #234". There is no value in keeping a main branch "clean" from TODO comments because it's somehow more hygienic. The code needs to be runnable at all times, even with incomplete features. Reaching zero TODO's before a product ships is a matter of grepping for the strings.
    - 7y ago