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.

Wednesday, June 11, 2008

Why Wicket Is Different

Eeelco Hillenius says it well on the Wicket mailing list:

Wicket supports private state for individual components, whereas the
traditional (REST) pattern assumes to take the state out (to string
based request parameters) and up to the request level. The big
difference is that without using a framework like Wicket, you can't
really create self contained components. You have to ensure that state
gets passed in any URL that is generated on a page, ensure the
parameters are properly scoped, have to worry about how to serialize
and de-serialize (from regular objects to strings and vice versa),
etc.

You can test this by creating a Struts app where you create a pageable
list. You'd append parameters for e.g. the page number and query to
every URL that passes back to the page, even if the link you are
constructing has nothing to do with the pageable list. Just the fact
that it is on the page means you have to pass the parameter. That by
itself is doable - though destroys encapsulation -; the problems
really start when you decide to move/ reuse the 'component' to/ in
another page, and when e.g. you add more things to the pass that need
to pass state like for instance tabs.

That really sums up my experience, too: you can use the wildest components and just not care about how they are implemented.