Re^2: What is your practice for code documentation?

Replies are listed 'Best First'.
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]

Replies are listed 'Best First'.

Re^3: What is your practice for code documentation?
by jethro (Monsignor) on Jun 26, 2008 at 00:13 UTC

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]