I find it weird to use TODO for something you don't actually have to do. But you're apparently not the only one to do this, and as long as everyone who's working on the same code is on the same page it's fine I suppose.
I think in these same three categories but label them TODO, T0DO, and TOD0, respectively. I like that they look roughly the same when visually scanning through a file but are easy to grep for separately.
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.
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'".
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.
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.
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
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+...`
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.
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.
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.
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.
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.
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):
> 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.
- 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.