151–153 of 153 posts
Earlier quoted context omitted.
But code doesn't always explain why it is the way it is.
It does a hell of a lot better job than comments. I can't believe you've got me justifying this policy. But it does seem to work. shrugs
Earlier quoted context omitted.
…and on the reviewer(s) who accepted the code change even though the comments no longer match the code.
I agree, but git and most code reviewing tools I've used only show a few lines of surrounding context so the reviewers might not even realize there's a comment further up that needs updating.
You can't really judge any of this if you're just eyeballing a diff. Diffs are just the starting point for a review, and while tooling could make this easier, the full file is always just a git checkout away.
Earlier quoted context omitted.
Comments are "reached for rarely and last". Whatever shortcomings comments have pale in comparison to being faced with and trying to figure out undocumented or too sparsely commented code, which, in my long experience, has been an order of magnitude more prevalent than sufficiently documented/readable code. Heck, even a wrong comment is sometimes preferable to no comment if it at least gives me a clue as to what the…
I personally strive for code that can be read as a sentence, especially in complicated sections of code. This sometimes leads to weird intermediate variables which might look superfluous, e.g. intermediates like: foo_has_at_least_1 = len(foo) >= 1 (not a great example, usually it’s a bit more semantics. than that) but later code using those intermediates reads as english, which can reduce cognitive load when reading…
The only time I ever feel the need to leave comments is to explain code that doesn't appear to be needed or isn't obvious why it exists. Usually this comes from agreed upon technical debt, short notice requirements with tight deadlines, or some other form of tradeoff.
"We're doing a simple check and throwing an exception here since we have work to introduce a more comprehensive permission system in xyz epic"
or something like
"There's a complicated race condition in xyz so we're doing a simple sleep here since the proper fix involves introducing a distributed lock"
Sure those types of things are cases you want to avoid but unfortunately you occasionally end up there anyway and leaving a short explanation about a compromise is better than ambiguous code that appears to serve no purpose