5 ms·

I add and grep for the following: - FIXME: this is clearly broken/wrong and highest priority - XXX: this is “ugly” or assumes wrong things, probably higher th

I add and grep for the following: - FIXME: this is clearly broken/wrong and highest priority - XXX: this is “ugly” or assumes wrong things, probably higher than next - TODO: at some point, implement a whole different approach/category/branch - NOTE: code comment with a higher importance than just random comment NOTE: I work a lot with old/unmaintained codebases where “code is truth”, so there is no “jira ticket creation” but amending things as you read.

radlad 1y ago
This is pretty much what I do too. `XXX` is "Look here! This is important!" or "You might not expect this!" I rarely use NOTE, but I have on occasion.
- jackpirate 1y ago
  What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.
  - pisipisipisi 1y ago
    Amsterdam.
  - slongfield 1y ago
    It has some ancient history as a morse code distress signal: https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03800_1._DISTRESS_AND_URGENCY_SIGNALS.htm https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03... And it shows up in some old BSD code: https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
  - 1659447091 1y ago
    I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999): https://www.oracle.com/java/technologies/javase/codeconventions-programmingpractices.html#395 https://www.oracle.com/java/technologies/javase/codeconventi...
  - zahlman 1y ago
    Unclear, but we do have https://www.catb.org/jargon/html/X/XXX.html https://www.catb.org/jargon/html/X/XXX.html > Some hackers liken ‘XXX’ to the notional heavy-porn movie rating. This seems plausible given the older culture ("this is metaphorically dirty, and therefore like porn", insert puerile snickering) and I can recall old jokes about "searching for" these markings. But I think it's also just about it visually standing out - the X character filling the terminal display cell with sharp lines.
    - o11c 1y ago
      Hm, this made me wonder about the use of XXX as a label for alcohol bottles in cartoons. It turns out it refers to "moonshine that has been distilled 3 times, reaching very high alcohol content".
nonethewiser 1y ago
Great in theory but these conventions are meaningless without tooling IMO. Assuming you are working in a team. Which is not to say they are meaningless - maybe there is or should be tooling for this.
- olowe 1y ago
  The godoc[0] tool provides minimal support for doing something with these comments via its “-notes” flag. It renders any TODOs (or BUG or whatever can be specified by regexp) in the code docs web page. I personally wouldn’t go beyond a single type of note but just having them show up together in the code documentation may be handy depending on the workflow. [0]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc https://pkg.go.dev/golang.org/x/tools/cmd/godoc
ericbarrett 1y ago
For me, XXX is a mental note to "fix this before your next pull request." If I'm being serious I'll set up CI to reject any code with a comment containing this string. So in that sense it would be the highest priority.
p0nce 1y ago
I'm using: - TODO: will be needed before release, mandatory or else turn into another category. Blocks release. - FUTURE: will be turned in to a TODO eventually, optional, often architectural - MAYDO: nice to have, very optional - PERF: do this if more performance is needed + some semantic tags related to domain Opinion: TODOs are NOT code smells, they accrue around the most valuable parts of the codebase.
- zahlman 1y ago
  I like these, although I wonder about the value of speculating about a performance optimization while neither just doing it nor profiling.
  - sfink 1y ago
    It's just saving the next person the trouble of thinking up and documenting the same approach you thought of while writing the code in the first place. As in, you know it doesn't matter now because the overall thing is plenty fast enough, but you can imagine a future where performance starts showing up as an issue and you wnat to leave a breadcrumb saying "this fruit here, it's a-hangin'".
  - Nadya 1y ago
    Very useful for flagging any O(n^2) that make assumptions about the size of N because N is not expected to exceed a certain size. Especially for when N inevitably exceeds that size. Documenting it saves the poor dev doing profiling in the future a bit of effort so they can come up with the better solution that you failed to come up with when writing the code. Often times code has to be written and committed and I don't have the time nor the brains to come up with a novel solution that solves a future performance issue that is not yet and is not expected to ever become a performance issue.
  - kreco 1y ago
    I take it mostly as "I'm aware that it's algorithmically slow and could become a bottleneck if it scales but I have no time to profile it right now" so you create a note to point this out. TL;DR: it's just a "TODO profile this".
cjbgkagh 1y ago
I do something similar, I place an assertion instead of FIXME for code paths that are not yet finished and can be avoided. My TODOs are associated with possible tasks including a refactor for performance or clarity. My NOTEs are for tracking historical information and to capture thinking at the time that would not be immediately obvious from looking at the code.
jansan 1y ago
I have often thought about doing exactly this, but one thing that always made me hesitate was the fact that nobody else seems to be doing it. Now that I finally see that others are actually using other labels than TODO I may actually start doing this, too.
marksomnian 1y ago
I like this style. In a project I worked on we had CI reject any FIXMEs outright and any TODOs that weren't accompanied by an issue ticket[^1], so the hierarchy would be FIXME: I am leaving a note to myself to not get distracted, but this code is not considered finished/mergeable until it's resolved XXX: this needs fixing soon, but the code will still be functional without it TODO: this needs revisiting but the code is perfectly useable without it - a lower priority XXX NOTE: this does something unusual and you need to bear in mind while working on this code [^1]: the value of doing (or not doing) this is a subject that has already been extensively rehashed in sibling comments
- echelon 1y ago
  NB(username,YYYY-MM-DD): Important documentation about XYZ thing that might break if you do something wrong. This is essentially a real comment, but calls for extra attention and care. [1] TODO(username,[TICKET-ID,]YYYY-MM-DD): Something left not done, optionally with a (Jira) ticket. If there are multiple authors or DRIs, replace `username` with `ldap_1+ldap_2+...` [1] https://en.wikipedia.org/wiki/Nota_bene https://en.wikipedia.org/wiki/Nota_bene
loodish 1y ago
Absolutely. The ability to search for these flags before a commit, during a review or release is so valuable.

radlad 1y ago

This is pretty much what I do too. `XXX` is "Look here! This is important!" or "You might not expect this!" I rarely use NOTE, but I have on occasion.

jackpirate 1y ago
What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.
- pisipisipisi 1y ago
  Amsterdam.
- slongfield 1y ago
  It has some ancient history as a morse code distress signal: https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03800_1._DISTRESS_AND_URGENCY_SIGNALS.htm https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03... And it shows up in some old BSD code: https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
- 1659447091 1y ago
  I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999): https://www.oracle.com/java/technologies/javase/codeconventions-programmingpractices.html#395 https://www.oracle.com/java/technologies/javase/codeconventi...
- zahlman 1y ago
  Unclear, but we do have https://www.catb.org/jargon/html/X/XXX.html https://www.catb.org/jargon/html/X/XXX.html > Some hackers liken ‘XXX’ to the notional heavy-porn movie rating. This seems plausible given the older culture ("this is metaphorically dirty, and therefore like porn", insert puerile snickering) and I can recall old jokes about "searching for" these markings. But I think it's also just about it visually standing out - the X character filling the terminal display cell with sharp lines.
  - o11c 1y ago
    Hm, this made me wonder about the use of XXX as a label for alcohol bottles in cartoons. It turns out it refers to "moonshine that has been distilled 3 times, reaching very high alcohol content".

nonethewiser 1y ago

Great in theory but these conventions are meaningless without tooling IMO. Assuming you are working in a team. Which is not to say they are meaningless - maybe there is or should be tooling for this.

olowe 1y ago
The godoc[0] tool provides minimal support for doing something with these comments via its “-notes” flag. It renders any TODOs (or BUG or whatever can be specified by regexp) in the code docs web page. I personally wouldn’t go beyond a single type of note but just having them show up together in the code documentation may be handy depending on the workflow. [0]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc https://pkg.go.dev/golang.org/x/tools/cmd/godoc

ericbarrett 1y ago

For me, XXX is a mental note to "fix this before your next pull request." If I'm being serious I'll set up CI to reject any code with a comment containing this string. So in that sense it would be the highest priority.

p0nce 1y ago

I'm using: - TODO: will be needed before release, mandatory or else turn into another category. Blocks release. - FUTURE: will be turned in to a TODO eventually, optional, often architectural - MAYDO: nice to have, very optional - PERF: do this if more performance is needed + some semantic tags related to domain Opinion: TODOs are NOT code smells, they accrue around the most valuable parts of the codebase.

zahlman 1y ago
I like these, although I wonder about the value of speculating about a performance optimization while neither just doing it nor profiling.
- sfink 1y ago
  It's just saving the next person the trouble of thinking up and documenting the same approach you thought of while writing the code in the first place. As in, you know it doesn't matter now because the overall thing is plenty fast enough, but you can imagine a future where performance starts showing up as an issue and you wnat to leave a breadcrumb saying "this fruit here, it's a-hangin'".
- Nadya 1y ago
  Very useful for flagging any O(n^2) that make assumptions about the size of N because N is not expected to exceed a certain size. Especially for when N inevitably exceeds that size. Documenting it saves the poor dev doing profiling in the future a bit of effort so they can come up with the better solution that you failed to come up with when writing the code. Often times code has to be written and committed and I don't have the time nor the brains to come up with a novel solution that solves a future performance issue that is not yet and is not expected to ever become a performance issue.
- kreco 1y ago
  I take it mostly as "I'm aware that it's algorithmically slow and could become a bottleneck if it scales but I have no time to profile it right now" so you create a note to point this out. TL;DR: it's just a "TODO profile this".

cjbgkagh 1y ago

I do something similar, I place an assertion instead of FIXME for code paths that are not yet finished and can be avoided. My TODOs are associated with possible tasks including a refactor for performance or clarity. My NOTEs are for tracking historical information and to capture thinking at the time that would not be immediately obvious from looking at the code.

jansan 1y ago

I have often thought about doing exactly this, but one thing that always made me hesitate was the fact that nobody else seems to be doing it. Now that I finally see that others are actually using other labels than TODO I may actually start doing this, too.

marksomnian 1y ago

I like this style. In a project I worked on we had CI reject any FIXMEs outright and any TODOs that weren't accompanied by an issue ticket[^1], so the hierarchy would be FIXME: I am leaving a note to myself to not get distracted, but this code is not considered finished/mergeable until it's resolved XXX: this needs fixing soon, but the code will still be functional without it TODO: this needs revisiting but the code is perfectly useable without it - a lower priority XXX NOTE: this does something unusual and you need to bear in mind while working on this code [^1]: the value of doing (or not doing) this is a subject that has already been extensively rehashed in sibling comments

echelon 1y ago
NB(username,YYYY-MM-DD): Important documentation about XYZ thing that might break if you do something wrong. This is essentially a real comment, but calls for extra attention and care. [1] TODO(username,[TICKET-ID,]YYYY-MM-DD): Something left not done, optionally with a (Jira) ticket. If there are multiple authors or DRIs, replace `username` with `ldap_1+ldap_2+...` [1] https://en.wikipedia.org/wiki/Nota_bene https://en.wikipedia.org/wiki/Nota_bene

loodish 1y ago

Absolutely. The ability to search for these flags before a commit, during a review or release is so valuable.