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

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.

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

"Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."

Comment on Re^2: Programming is much more than "just writing code".

Replies are listed 'Best First'.
Re^3: Programming is much more than "just writing code". by Mutant (Priest) on May 09, 2007 at 16:08 UTC
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.	[reply]
doc changes clutter vc logs (was: Re^3: Programming is much more than "just writing code".) by doom (Deacon) on May 09, 2007 at 16:34 UTC
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.	[reply]