laziness, impatience, and hubris | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
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 In reply to Re^2: What is your practice for code documentation?
by ady
|
|