Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

Re: What is your practice for code documentation?

by moritz (Cardinal)
on Jun 25, 2008 at 17:36 UTC ( [id://693998]=note: print w/replies, xml ) Need Help??


in reply to What is your practice for code documentation?

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.

  • 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 ady (Deacon) on Jun 25, 2008 at 18:52 UTC
    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

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others pondering the Monastery: (7)
As of 2024-04-18 07:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found