[timr]

The problem is that the implementation of the 'why' can be scattered over many files, classes, functions, etc. So where to put the comments?

You put them everywhere that might be relevant, along with cross-references to other relevant code/documentation. Humans aren't robots -- redundancy is a good thing, because it helps our feeble minds more quickly reinforce key concepts.

[mercurial]

The first thing to know about comments is that they're sooner or later going to get out of touch with the code, unless you have some phase where you are going to review them in depth.

Obviously, redundant comments scattered across the code are even worse: out of sight, out of mind.

[timr]

That's the oldest, tiredest objection to commenting that you could possibly write. It's the first objection raised by every wet-behind-the-ears, new-grad coder. It's a cliche. It's also crap. Yes, unmaintained comments will go out of date. That's why you maintain them, just like you maintain your code. And don't argue that it's too hard -- writing code is harder, and you do that all day long.

Your first job as a professional programmer is making the rest of your team more productive by reducing the communication burden. Your second job is understanding old code. The amount of code you personally write is a distant third priority.

[mercurial]

Funny you should say that, considering the number of experienced coders who have a different opinion. I'm not arguing for no comments at all (especially regarding non-obvious things), but most of your code should be self-documenting, assuming sufficient domain-level knowledge from the reader. If it's self-documenting, comments are redundant.

[timr]

"most of your code should be self-documenting, assuming sufficient domain-level knowledge from the reader. If it's self-documenting, comments are redundant."

You're hitting on all the classic lame excuses. Self-documenting code is a myth, invented by lazy coders who would rather crank out code than write documentation, because it's more fun to write code. They're wrong, but they often don't know that they're wrong, because the same people who suck at writing documentation usually suck at reading code.

Clean code is a necessary, but insufficient precondition to understandability. Documentation is essential, because code can only tell you what -- it can't tell you where it should be used, why you should use it, how it should be used, who who should use it or when it's appropriate. And in any case, your code is never as clean or self-documenting as you think it is.

That said, I have no doubt that you're hearing these things from "experienced" coders, because our industry is filled with "experienced" people who suck at what they do. Also, these things are cliches for a reason. They get repeated a lot.

[mercurial]

Actually, that's what we use with a rather large codebase, and it works out pretty well. Different tacks for different people, I suppose.

[timr]

Not really, no. It's not a matter of opinion.

You can obviously get away with not documenting code, but you don't know what it's costing you. However well things are working out now, I can guarantee that they'd be working better and faster for your team if you spent the time to write good documentation.

[geoka9]

going to get out of touch with the code, unless you have some phase where you are going to review them in depth

I think treating comments as something that's done in a separate phase is the wrong mindset. Comments should be integral part of code and therefore change whenever the relevant code changes.

[mercurial]

Maybe, but it's not that easy. You're generally going to see a 3-lines-of-context diff, and the reviewer won't necessarily have the idea to read the entire file (or worse, go poking elsewhere in the codebase) to see if comments deserve changing.