My pet peeve is `XXX:`, which I see with distressing regularity in the codebase I work in. It’s non-specific, but vaguely ominous. Is it a TODO? A warning? A bug? An incantation to ward off evil spirits? Tell me!
I don't know if this is the exact incantation, but some IDE extensions will recognise some special comment annotations. TODO/FIXME support is in pretty much every IDE, but there are some special codes that some IDEs will recognise.
Visual Studio (not necessarily Code) will recognise TODO, HACK, NOTE and UNDONE, for example.
I'm not a huge fan of XXX as a warning, there are more descriptive names in caps available that your IDE will probably even autocomplete after using them for a while. However, the practice is common enough that it's just a General Programmer Thing, kind of like how some people prefer /* */ over // because they're just more used to it.
I use XXX to mean "this code is ugly and not the intended design, but I don't see a great way to fix it". If I did, I would leave a TODO with steps. The XXX is a formalized "ugh", a note for anyone reading my code later to glean that I was unhappy. Often times the hardest thing about reading a codebase is rebuilding that mental model on how the code is ideally supposed to fit together at the high level, and an XXX explicitly marks a conflict between the code itself and that vision, and explains why.
"XXX:" is short for "BULLSHIT:" or other profanity to me, generally imply that life sucks.
usually to indicate some horrible hack which is required because we can't quite blow up the codebase to fix it all, and i'm not thinking of a simpler solution today.
it also exists to point out that even though the code looks maybe mindlessly overcomplicated that someone shouldn't just come in and refactor it to make it simpler because it'll blow up some edge condition if you do that. They're the long-term nuclear waste warning messages of a codebase.
We had a recommendation in one of my previous companies to replace all TODO's with XXX. Their rationale was that the TODO tags sounded like an unfinished product to the customers. So they wanted to replace all those TODO labels with XXX so that the customers wouldn't find them when grepping. Even if they find a XXX label while reading the source they wouldn't have any clue as to what it is.
I use it occasionally as a heads-up about tricky functionality, or to point out something that should be read by future developers, so yes, like a warning. It's similar to `NOTE`, but more important. There's nothing to be done, so `TODO` wouldn't make sense.
I haven't seen `XXX:` anywhere, but it's immediately disconcerting as the icon is meaningless. If I have to reach-out to you to discover the meaning of some word you use, it's a bad word.
Does it really need to be something more important than NOTE? If you are working on the code you should be reading that NOTE anyways, so why not use a word with more specific meaning? Or even just IMPORTANT. Before this thread I would have never known what XXX meant, having never seen it before.
I suppose if its defined somewhere as a standard for everyone working on the code it may make sense. Just doesn't feel very intuitive to me.
I use it with parenthesized clarification. So `# XXX(dependency-version): Reason why we can't have nice things` is code that can be updated when `dependency` of at least `version` can be assumed. The clarification is there so that if the reason itself goes away, we can just remove the conditional. Repeat for things like `cmake-3.23`, `macos-10.14`, `python-3.8` and so on. It's just an easily greppable string and Vim highlights it differently.
jeroenhd|3 years ago
Visual Studio (not necessarily Code) will recognise TODO, HACK, NOTE and UNDONE, for example.
Java conventions mention XXX: https://www.oracle.com/java/technologies/javase/codeconventi...
Using XXX in comments goes back to 1978, according to https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/I'm not a huge fan of XXX as a warning, there are more descriptive names in caps available that your IDE will probably even autocomplete after using them for a while. However, the practice is common enough that it's just a General Programmer Thing, kind of like how some people prefer /* */ over // because they're just more used to it.
Jasper_|3 years ago
lamontcg|3 years ago
usually to indicate some horrible hack which is required because we can't quite blow up the codebase to fix it all, and i'm not thinking of a simpler solution today.
it also exists to point out that even though the code looks maybe mindlessly overcomplicated that someone shouldn't just come in and refactor it to make it simpler because it'll blow up some edge condition if you do that. They're the long-term nuclear waste warning messages of a codebase.
rob74|3 years ago
fractalb|3 years ago
imiric|3 years ago
marcosdumay|3 years ago
I haven't seen `XXX:` anywhere, but it's immediately disconcerting as the icon is meaningless. If I have to reach-out to you to discover the meaning of some word you use, it's a bad word.
Bedon292|3 years ago
I suppose if its defined somewhere as a standard for everyone working on the code it may make sense. Just doesn't feel very intuitive to me.
mathstuf|3 years ago