Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

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

by ady (Deacon)
on Jun 25, 2008 at 18:52 UTC ( #694016=note: print w/replies, xml ) Need Help??


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

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
  • Comment on Re^2: 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://694016]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (4)
As of 2022-08-15 06:01 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?