Seldom people document the 'Why' which is the most useful some years in as no one knows the 'Why' any longer and might make the wrong decisions in refactoring - also if you don't know the 'Why' you often scratch your head with WTF, though the reasons were sound.
"How" though, very much e.g. reference to the algorithm being implemented or the like if the code is unclear.
Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost.
More often than not, you only need a few jumps before reaching the change you're interested in.
I have a 1500LOC files with 1100 revisions right here, "git annotate" processes it in 2.356 seconds on a 2010 MBP, and PyCharm barely takes any longer (maybe 3s).
> How is my IDE supposed to know which of those revisions are the ones that I care about?
It does not care, it gives you a baseline annotation and if that's too recent you drill down into previous annotations.
No thanks. I’d rather have a comment inline in the code than add 3 seconds per file, and still have to go searching through the history.
Or as I've encountered on multiple occasions: your IT team is struggling to figure out why your network/version control/etc are extremely slow... 3 second queries are now taking 60 seconds... we will be rebooting servers a few times... and restoring backups... hopefully things are working better tomorrow!
Or what happens when you migrate to another versioning system? Where I was working migrated from MS SourceSafe years ago and a lot of comment history was lost in the conversion and apparently it wasn't worth the time/money to figure out why only half the comments made it over.
I'm sure there are more scenarios.
The point is: comments in plain-text source files can be invaluable.
Which is exacerbated by everyone's IDE now querying VC for every file!
That's what annotate/blame is for.
> Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost.
If there was "no reason at all", it won't be in a comment either.
Except you can't trust comments. Even assuming the comments were relevant at one point, they don't get updated as the code changes, and as new code gets added they can drift away from the original code they were supposed to explain.
Commit messages don't drift, they're immutably bound to the changes the commit performs.
And because they're not bloating up the code it's much easier to be clear and verbose in commit messages than it is in comments, the author can easily explain things which seem obvious to them but may not be so for a reader in a few months or years without lowering the overall readability of the code which is not the case of comments.
People will criticise comments as "obvious" and "unnecessary", I've yet to have a colleague or contributor criticise a detailed commit message for any other reason than the commit message being wrong.
> It should not be detective work to figure out why some code is written in a non-obvious way.
Get proper tools. Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory.
That works until the VCS history is lost. For an on-topic example, this usually happens when a formerly closed-source code is released to the public: only the final state of the source code is released, with none of the VCS history. This can also happen when changing to another VCS; often the history is kept only on the former VCS. Some projects have gone through several of these events; I challenge you to find early StarOffice history when trying to understand why some piece of LibreOffice code is written that way.
And there's also the tendency in some places to reference bug tracker issues in commit messages. Said bug trackers tend to have an even shorter life than the VCS. "Fixes issue #1234" is useless when issue 1234 was on the old bug tracker, and both it and the new bug tracker were lost when the company was acquired and migrated to a third bug tracker.
Comments you can at least make an effort to keep up to date. Especially if have a policy that all comments should actually be relevant.
Comments shouldn't be obvious and unnecessary. They should explain things which cannot be inferred from the code itself, eg,
// have to call reset() twice here because the XZW API has a bug which restarts the server if reset is not called twice. See ..."Doing this here because x,y,z, maybe better to do a,b,c later on but would have to do d,e,f" and so on.
I do worry a bit about doing it sometimes because in its own way it admits some sort of shortcomings or such... but still I do it.
When reading other people's code the why is often the question I'm wondering but rarely anyone says.