[donatj]

In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments.

They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.

[ibejoeb]

Bang on. This practice has changed in the hosted, PR-based collaboration world. Instead of embedding this kind of thing in the source itself, it's written up in these constructs that exist outside. Then they go missing or are just undiscoverable, at least until it's too late.

[jrochkind1]

I quite often try to investigate those constructs before changing code I am not familiar with. Look at `git blame` to figure out commit(s) that touched the code. Try to figure out what PR they were part of to read the PR description.

This isn't as easy as I'd like, so I don't do it as much as I'd like. It's interesting to contemplate what sorts of UIs could make it easier.

At one point I distinctly recall github web UI for a commit showing you what PR(s) the commit was in -- but I'm having trouble reproducing that now, so maybe it no longer does? Or maybe i am confused and imagined it.

[ibejoeb]

Yes, it's a lot of work, and it's very possible to just lose that information, even if you are committed to sticking with the platform.

It's also not unique to something like github. It was still possible to lose context when we used to email patches around. But I'm certainly encountering it more now, because I really do think the behavior has been influenced by the tooling. PRs are great, but in a case like this ("it looks dumb but it's not") the notes really ought to be inline. It's not practical to encourage a protocol wherein, upon every encounter with something fishy, we go traipsing all over trying to find out if someone, somewhere, sometime explained it.

I think my general point is that source management isn't the ideal place for the "whys" of things.

[jrochkind1]

I'm not sure.

In the present case where it is very hard to track, ok. Of course we don't want to be forced to "go traipsing all around", and often won't bother if that's what it takes.

But comments are not a great place for it either. They can take up space, make source files harder to read as a whole (interupting your flow when you don't need them).

And a comment in source code is a commitment (often unmet!) to keep them _up to date_ and matching the code they describe, as it changes (as OP mentions), when actually for "why"/motivation, point-in-time comments at a point of _history_ (or several points as it changes) would often be quite sufficient, without the maintenance burden.

A world where many (not all) can be kept out of band in the source management system, as point-in-time historical notes, rather than in the source code itself and where it is very easy to track them down in source management, to me seems actually ideal.

I realize of course that world is not quite what we've got.

But for instance, when I _do_ track down the actual relevant (eg) PR's, especially aged ones, the _entire discussion history_ captured in them (possibly multiple PRs and commits over time) can often be _super valuable_, to have that context that there is no feasible way to embed in source code comments. Comments themselves are never going to be as good as we want, and we often end up doing "code archeology" regardless, what if it were super easy and frictionless to do?

I really wish (eg) github spent more time on UX to make this history easily followable without all the "traipsing around". But apparently there is not customer demand?

[ramses0]

...and the epic "comment the empty `else`-block":

   ... } else { /* no action needed, enterprise users should not frib or frob... */ }

[klysm]

I always try to think through all of the walls before I start on something like that, but it’s usually not clear until you hit it.

[tuatoru]

Came here for this. The "why not" comments are the most valuable.