http://qs1969.pair.com?node_id=694016


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