Beefy Boxes and Bandwidth Generously Provided by pair Networks
Come for the quick hacks, stay for the epiphanies.
 
PerlMonks  

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

by jethro (Monsignor)
on Jun 26, 2008 at 00:13 UTC ( [id://694075]=note: print w/replies, xml ) Need Help??


in reply to Re^2: What is your practice for code documentation?
in thread What is your practice for code documentation?

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.

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

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://694075]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others goofing around in the Monastery: (5)
As of 2024-04-24 12:52 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found