Re: What is your practice for code documentation?

automatic generation of documentation is only useful if that documentation
a) provides a view for a programmer of that code that he can't as easily get from looking at the source code or
b) provides a document that makes interfacing/using with the code possible without needing to look at the code

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.

Comment on Re: What is your practice for code documentation?

Replies are listed 'Best First'.
Re^2: What is your practice for code documentation? by chromatic (Archbishop) on Jun 25, 2008 at 20:43 UTC
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.	[reply]
Re^3: What is your practice for code documentation? by jethro (Monsignor) on Jun 26, 2008 at 00:13 UTC
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.	[reply]


P is for Practical
	PerlMonks