[stevesimmons]

What you write in your first para is so self evidently true, at least to me.

I simply cannot comprehend the mindset that views comments as unnecessary. Or worse, removes existing useful comments in some quest for "self-documenting" purity.

I've worked in some truly huge codebases (40m LOC, 20k commits a week, 4k devs) so I think I have a pretty good idea of what's easy vs hard in understanding unfamiliar code.

[soulofmischief]

As the late Chesterton said, "Don't ever take a fence down until you know the reason why it was put up."

A lot of people think comments are descriptive rather than prescriptive. They think a comment is the equivalent of writing "Fence" on a plaque and nailing it to the fence. "It's a fence," they say, "You don't need a sign to know that."

Later, when the next property owner discovers the fence, they are stumped. What the hell was this put here for? A prescriptive comment might have said, "This was erected to keep out chupacabras," answering not what it is, but why.

You might know about the chupacabras, but if you don't pass it on then you clearly don't care about who has to inherit your property.