Hacker News Reader

Hacker News

Comment by pisipisipisi | Hacker News Reader

Full thread

pisipisipisi

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.

View on HN

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.

I like these, although I wonder about the value of speculating about a performance optimization while neither just doing it nor profiling.

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'".

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.

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".

Personally I use

FIXME: something broken that needs fixing

TODO: potential features/improvements

WARN: noting complex edge cases/weird behaviors

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.

MAYDO is a nice one.

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+...`

[1] https://en.wikipedia.org/wiki/Nota_bene

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.

[0]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc

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.

What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.

Amsterdam.

It has some ancient history as a morse code distress signal: 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/

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):

https://www.oracle.com/java/technologies/javase/codeconventi...

Unclear, but we do have 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.

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".

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

Reply on news.ycombinator.com