I don't think that any of the developers in the project have looked at the extracted documentation more than once.

I think it's totally irrelevant if they looked at the extracted documentation or not - the question is if they looked at it all. If they read it inline in the source code you just wasted one run of your extraction script.

If they didn't look at it at all, you'd better spend your time with writing tests instead of documentation. Tests also document things in a way, and are more valuable if your colleagues don't look at the docs.

BTW I was a bit confused, because you seem to be talking about code that is neither visible to a customer (through an API or a command line interface), nor regarded as "re-usable", because after your own logic, code has to be documented if it meets either of these two criteria. If you have large amounts of code meeting none of these criteria, chances are that documentation isn't your biggest problem at all.

If they didn't look at it at all, you'd better spend your time with writing tests instead of documentation

That seems a rephrasing of the main point of my post : spend your time improving the code quality (clearity, immediate understandability - by refactoring, writing tests &c) instead of investing in more extensive templated commenting for automatic doc report generation (as is popular in many coding environments these days).

Our specific code must be understandable - not to end customers (they never see it, but they do experience its (possibly lack of) quality) - but potentially for reuse and primarily for maintenance and further development.

Other projects may have other requirements, and thus other goals. As Arnon states in a footnote :

* I don't underestimate the value of generating full documentation when there's such a requirement from a customer. I would prefer to convince a customer that having such a Write-Only document is a complete waste of time and trees but sometimes you can't help it. Generating documents in these situations can be a life-saver.

allan

DBI.pm#SYNOPSIS

In a single page you've got pretty much everything you need to effectively use the DBI interface, laid out intelligently showing the basic groupings of methods. You'd need a pretty impressive AI to auto-generate that!

-sam

Indeed, the synopsis is extremely valuable. Unfortunately many people leave out a very important part: the result of the code displayed. In my modules I use the same format as I use on PM code examples:

CODE

__END__
OUTPUT
[download]

For instance, the synopsis in List::Extract would be near useless if it wasn't for the output.

It's easy to generate (and manually test) this by simply typing perl -Mstrict -w and then pasting the code. On your screen you now have the code, __END__, and the output following that, ready to be copied back.

But the module may change, and an important feature of this format is that it's easy to test it. I've written, but not released, Test::Synopsis which extracts the code from the POD, compiles it, and if there were no errors or warnings, the output is compared to what's after __END__ (if anything).

It has proven to be useful to me. I'm considering it for release.

lodin

To achieve a) it isn't enough to just extract comments (handcrafted or not) or generate them, both provide no new information and should be visible in the code itself (if they are not hidden by bad coding). Arnon hits the nail on the head here. There might be some use for diagrams showing the call or object hierarchies but I don't have much experience there so don't know.

b) is impossible in the general case (at least without true artificial intelligence). One could argue that is what is done with the POD-pages, but there you need to write the docs all by yourself, the only difference to separate documentation is that with POD the information is closer to the code.

Btw, I don't see refactoring as a substitute for documentation. No code is that readable that a comment can't tell you faster whether or what part of that code you need to read.

No code is that readable that a comment can't tell you faster whether or what part of that code you need to read.

Comments lie. Even good tests rarely catch incorrect comments.

Depends on the viewpoint. It could be argued that the code is the one lying. ;-)

That is especially true for interface definitions. Discrepancies here are usually viewed as bugs, not as faulty documentation. Why should this be different for internal documentation? It is the interface to other programmers and should be correct

In situations where the software has to be finished yesterday, documentation is secondary. But when you've got the time to document, you have a choice. If you care for your documentation, then the documentation shows your intent. And the code that doesn't do what is intended is buggy. Naturally out of date comments can't be avoided entirely, but it is the importance that you give their correctness that makes them valuable or noise

The problem with this is in in projects with more than one programmer. One who doesn't take the comments serious is enough to destroy the effort of the rest.

Stopping with my sermon now. Just let me add that I update the comments in my projects meticuosly as I have a bad memory and depend on their correctness. But I don't comment much in the code, I put the comments at the beginning of subs and methods to detail their tasks and their parameters.

Chapter seven ("Documentation") of Perl Best Practices is well worth a read, no matter what language you are using, providing sound advice on separating user from technical documentation, how to subdivide your technical documentation, discursive documentation, algorithmic documentation, commenting, and more.

To me, I think the biggest key is to remove as many codesmells as possible. In doing so, the code becomes more self-evident. And, with a little reflection, that makes perfect sense. A codesmell is a place where someone goes "Why would you do that??" If you remove a codesmell, you remove a question in the reader's mind.

That said, there are places you will always need to explain something. About 6 months ago, I started signing and dating all my comments, especially in projects where I'm the only developer. Obviously, I know I made the comment. But, as it turns out, the date on the comment has proven more useful. This is because knowing the order of the comments helps to remind me what my thinking was at that time. Since I started doing that on a $work project, I have come back to DBM::Deep where I don't have dated comments and the contrast was very stark. I feel lost without that historical context.

If I need more than 120 characters to explain something, it's either a horrible problem with something I'm using or I screwed up somewhere. Usually, it's the latter and I need to rewrite. So, the comment gets an XXX (or TODO) on it.

As for POD, there is very little in the way of auto-generated POD. All that stuff is written by someone, often the developer. I would love to see more non-developer-written POD as that documentation tends to be of higher quality. (This is especially true for my modules!)

I prefer good, well structured, clean, and cohesive code to the best comment any time. Perl, which is, to me, a language that is structured as a spoken language (assuming we would speak in routines, loops and variables), shouldn't (theoretically) be commented more than the obligatory synopsis, the API, and the overall i.e. the "man". If you have to explain anything beyond the overall things, you may need to rethink your code, not your comments.

If your code needs a comment to be understood, it would be better to rewrite it so it's easier to understand. (Notes on Programming in C - Rob Pike)

(Oh, and "hits the argument on the head and drives it right home"?)

Think about it this way:   how well does a telephone directory describe a town?

When I am looking at the documentation for a piece of computer software, sometimes I am looking for a directory. I really do just want to know where a particular place or thing is. But... not most of the time. In fact, almost never. No.

What I really want is:   to read the original developer's thoughts. I want to get a glimpse of her intent when she designed and then wrote that particular piece of code. Truly, the final software is very-much an expression of that, and this is something that no amount of computer-generated recyclables will tell me.