[Alexandervn]

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

In my projects (usually building websites or webapps) I therefore add a 'readme.md' to the root of the project and document general choices there.

[randomdata]

I think inline comments are fine for when you are doing something really weird (for, say, performance reasons) that needs explanation, but if you want to document the why of the entire codebase, I feel the test suite is a better place for that.

Not only can you explain the why and demonstrate usage in a logical manner, but you get some consistency checks from your documentation for free.

[ZoFreX]

I wish more projects would document the more "macro" knowledge about their code - the infrastructure and organisation, for instance, or the metaphors used throughout the code.

[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.

[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.

[NateDad]

Well, that's an overarching why. But why you're doing this one specific thing on this line, which might look wrong or overly complex or just bizarre... you need to comment those.

  // foo library throws an extra two bytes at the front of the
  // array, even though that isn't up to spec, so we have to
  // strip them out here.