Huge discussion about JavaDoc ...and no one cares about Fat Clients :-)
My opinion about JavaDocs in the interview Better Programming With Java EE on java.sun.com caused an interesting discussion on theserverside.com and starting at javaworld.com as well. People started to question the usability of JavaDoc - and I have to disagree at this point. JavaDoc is absolutely useful and essential for the maintainability of the product. Here my condensed opinion about JavaDoc:
- IDE-generated JavaDoc is worthless. It simply cannot contain any additional information to the source.
- Obvious methods (e.g. accessors) shouldn't be commented - it's a good way to obfuscate the rest :-).
- Documenting the intention and reasons for certain class or method is the key for good JavaDoc. Instead documenting: "this method is executed in the NotSupported transaction context", it would be better to explain why you chosen this particular transaction setting and suspend so the transaction...
I really wondered about the discussion about JavaDoc - but actually no one complained about this statement "Therefore, a fat client with a local embedded database, such as Java DB, is the simplest possible solution -- everything else is a workaround.". I especially used the term fat client - which causes massive reactions in general :-).
Several years ago, we started to build a corporate application. The UI, as well as business logic (these days it was Hibernate with Eclipse / SWT) were deployed to the desktop machine. We were able to throw away tons of superfluos layers, patterns and indirections. Beyond that - we were able to use Data Binding directly to the domain objects and work "per reference" instead of "per value". The only problem was: I as chief architect used the term "Fat Client" just not to confuse developers. I was fired - and the several companies experimented with SOA-like approaches (some really esotheric).
After the experimentation phase I was contracted again, and we switched back to the fat client architecture - however I use the term "Rich Layered Client" then. It was a huge success. The project is in production now, several other projects try to follow the same architecture. In this particular case, it just wasn't necessary to distribute layers to different JVMs and introduce so an application server.
I presented some ideas of the "Rich Layered Client" architecture at the JavaONE 2007, with some interesting feedback.
I'm lazily (because I'm pretty busy) following those discussions and I was wonderer as well why people engage so easily in discussions on low-level stuff (e.g. javadoc, closure syntax, etc...) and there are much less discussions on design and architecture. After all, it might be as simple as the fact that there are much more programmers around than architects and I shouldn't be surprised. But it hurts me somehow all the same.
Posted by Fabrizio Giudici on April 05, 2008 at 03:10 PM CEST #
... I was **wondering** ...
Posted by Fabrizio Giudici on April 05, 2008 at 03:11 PM CEST #
Almost agreed. But I don't believe in "pure" architects - only "coding" architects. "Powerpoint" architects cause too much damaged in the past :-)
thanks for your post!,
adam
Posted by Adam Bien on April 05, 2008 at 06:09 PM CEST #
Adam, I was one of the folks involved in that "large discussion", so no need to rehash my comments on that topic here... I will comment on the "fat client with local embedded db" thought.
I actually think, underneath it all, that we have the same basic philosophy, and you can of course correct me if I'm wrong, but based on what you've written I believe we're on the same page...
Any coding project should be designed and coded as simple as possible, and no simpler.
That's the maxim I always work by, and it has served me well. I frequently bump up against other architects I work with because they are thinking in terms of this pattern, that design concept, this abstraction and that model. I instead think in terms of what's *really* the underlying goal, and what's the simplest way I can pull that off? Once I have that answer, only *then* do I think about adding all the other typical complexities we all deal with every day.
Sometimes complexity is inevitable, no question. Some problems just don't *have* a particularly simple answer. Other times, complexity is actually desirable, usually in the name of needed flexibility. I have no problem with those ideas, I agree completely.
But it's when people take a relatively simple problem and over-burden it with all sorts of ideas and techniques that they've heard about over time, all the while thinking they are creating an elegant architecture because it dutifully implements every advanced CS technique there is, it's at that point I believe they've lost their way.
I've seen people creating factories for things that arguably didn't need a factory... I've seen people making all sorts of things singletons for no obvious reason... I've seen people go out of their way implementing all sorts of read-write locking code when simple synchronization would have sufficed... I've seen people create a 30-class-deep hierarchy *just in case* someone wanted to extend the code at any of those 20 points... I've seen people choose EJBs over simple REST-based remote procedure call methods because "EJBs are the way to go for distributed code"... I've seen people refactor code into 30 different methods, each 2-3 lines long, because it supposedly enhanced the readability of the code... I've seen people create DTOs for two fields of data... I've seen people choose this persistence library or that when basic JDBC and SQL would have more than done the job... and so on.
I'm not saying any of that stuff is inherently bad, nor is it necessarily wrong in any particular case. All I'm saying is that if that kind of stuff is coming out of your initial design sessions, either (a) you're designing something inherently very complex and the flexibility is required, or (b) you're *way* over-thinking things. If the answer is (a), then fine, so be it... but I've seen *way* too many cases where it's really (b), but the architects/developers only know how to think in terms of (a), which is a Very Bad Thing(tm), IMHO.
Posted by Frank W. Zammetti on April 06, 2008 at 09:07 PM CEST #