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.