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.

[BrowserUk]

If (module/unit) documentation only ever consisted of interface specifications, then (perhaps), POD would be fine. But, all too frequently, it also has to contain a mountain of stuff that is essentially unrelated to the code.

Whether it's algorithm explainations, or market research, or comparative studies or whatever else might be useful or required by the users of a module. But often this stuff is of no consequence to the programmer maintaining the module.

To conflate user documentation with programmer documentation is a bad idea. Even if the modules users are also programmers at the next level up, mixing the two types of documentation together means that it serves neither group well.

There's also the problem that purely textual changes, from typos to reattributions to rephrasing of prose can trigger RCS trails associated with the code that shouldn't be. Documentation also belongs in the RCS system, but as independant entities to the code, so that documentation changes do not affect the revision history of the code and vice versa.

[Mutant]

I think you have some valid points, but there are some issues with having separate module documentation files. Apart from documentation not being directly under the maintainer's nose as I mentioned above, a lot of tools expect the docs to be in the same file as the code, so browsing it becomes an issue.

This could fairly easily be worked around, but on balance, I think it becomes a matter of personal choice, rather than one way being inherently superiour to the other. (There are ways to work around the problems of having it all in one file, such as having a good standard of what the format for each module should be, to keep out-of-place info creeping in).

But I think this is a separate discussion to your original point, which was on the merit of code annotations.

[doom]

There's also the problem that purely textual changes, from typos to reattributions to rephrasing of prose can trigger RCS trails associated with the code that shouldn't be. Documentation also belongs in the RCS system, but as independant entities to the code, so that documentation changes do not affect the revision history of the code and vice versa.

This is actually a very good point (though I have to say I thought that I was the last person in the world using RCS for version control). Documentation and comment changes are more common than actual code changes (at least if you're someone like me who does re-write it to keep it up-to-date), and it might be better if those changes weren't cluttering the logs.

Damien Conway recommends against putting project documentation in a dedicated *.pod file: he argues that there's no way to be sure the *.pod will get installed correctly in some place where it can be found, but if it's inside the *.pm file, you know it's always going to be with the code.

In part, under the influence of Conway, I've been sticking to a documentation style where more tangential/higher-level material is confined to some pod at the bottom of the *.pm file (I'm a fan of "MOTIVATION" sections myself, they're often the key thing that makes clear whether you want to use a module at all). But in a multi-module project, I find I definitely have a problem with repeating myself too much, e.g. stating the project's purpose over-and-over again...

There are some clear advantages with having a project overview pod file elsewhere.