Tuesday, June 17, 2008

Prose vs. Javadoc

I've been thinking about documentation lately. I believe we often concentrate too much on the small scale documentation. We write Javadoc for every method, but what is usually sorely missing is documentation about the big picture. And I don't mean UML diagrams, I mean good old prose describing what a system does and how it goes about that.
Any reasonably competent programmer can figure out what a method does if he or she understands how a system works in general.

No comments: