💾 Archived View for thrig.me › blog › 2024 › 10 › 23 › comments.gmi captured on 2024-12-17 at 10:42:18. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
Who doesn't like code comments, especially comments woefully out of date with what the code does, or play-by-play on what the code is doing.
# increase the value by two
$value += 2;
Those are bad comments, and some would argue bugs, as the comments really should be relevant, agree with the code, etc. There are also good comments,
(let ((outcome (roll attacker defender)))
(when (is-player attacker) (setf outcome 0))
...
not present in the above example, where the programmer put in a temporary debugging line to make the player always miss, but did not mark this temporary line as such. If you commit the change with a bunch of other things, forget about it, you may then at some point later on wonder why the player misses so much. Here a good comment can direct your attention to the temporary line,
(let ((outcome (roll attacker defender)))
(when (is-player attacker) (setf outcome 0)) ; TWEAK FIXME DBG XXX
...
where hopefully the shouty caps and something easy to see will hopefully be seen at commit time (you are reviewing the diff, right?) and easy to search for during a post-coding-craze cleanup session (when you were too deep in the code to deal with any review stuff). I probably wouldn't use all four of the tags, one should be enough, and you probably should have some guidelines on what tag to use where so that putting in the tags becomes motor memory (possibly assisted by an editor macro to quickly put in various common tags).
A problem here is if too much of the code gets littered with XXX or whatever, in which case the tag now probably has too much noise for the signal, so there is a bit of art and skill in the appropriate use of tags, cleaning them up, whether a tag should instead reference a ticket number (or not), etc.
<@dana9610> hmm good habit to get into. Maybe "HEY_DUMBASS" would
work for me