Re: Programming *is* much more than "just writing code".

[Mutant]

I think you've muddied the waters somewhat by saying:

Documentation of code is vitally important for successful, ongoing projects, but comments are not documentation, and it has no place in source files.

If you're talking about POD here, then I think that's distinctly different to comments. POD (or JavaDoc or whatever you happen to be using) is documentation, not comments. It tells a user of a module how it's interface works. The fact that it's kept in the same file as the source code doesn't make it a comment. In fact, I think it's much better to keep it there, than some separate file that someone may not even realise is there when they're updating the code (one reason why doing this has become an industry-wide standard).

As far as actual comments go, I think you tend to find roughly 3 types:

1. Those explaining what something does
2. Those explaining how something does what it's supposed to do
3. Those explaining why something does what it does

I tend to think #1 is OK in small doses. It can make code more readable, which to me trumps the synchronisation issues you're talking about. And at any rate - if kept high level enough - what a particular piece of code does isn't likely to change that much (at least without the whole block of code getting wiped or re-written, along with the comments), so it's not likely to get too out of date.

#2 is either there because whoever maintains the code is assumed to be stupid, or the code itself is obfuscated. In the latter case, the comments are really a red flag (i.e. not evil in and of themselves, but a good sign some refactoring may be needed).

#3 is often needed if the system-level design is (or has become) poor. This is true of quite a lot of the code I'm currently working with. In these cases, the ideal situation is to fix the design. However this is not always practical. This is where these comments can become useful. They shouldn't be a subsitute for system documentation, but they can make it much easier to pick up the context when reading code (and even more so if they reference system docs).

So on the whole, I don't really think extensive comments in and of themselves are evil, but they can often be pointers to other issues.