I was curious to see if I could generate a diagram that showed how all the services inside Tapestry 5 are interconnected. In the diagram, solid lines are dependencies, dashed lines are contributions, and dotted lines represent a services that listens to events from another service.
The final diagram is a bit complex. Ok, that's a tremendous understatement. Yellow nodes are public services, grey nodes are internal services, and orange nodes are simple beans (contributed into services) ... those beans, though, may still have their own dependencies. I think OmniGraffle choked on the complexity (why do some of the lines zip around so aimlessly?) and kind of "phoned it in" in terms of layout. I had hoped for something that could go on a T-shirt.
Worse yet, this is only a partial diagram; I didn't cover many of the dependencies that arrive as contributions to services (there's just a few of those in there). Those contributions would show up as even more orange nodes; these additional nodes would provide connections to many of the outliers that appear to be unreferenced.
Is this good or bad? Is it too complex? Can it be simplified? Does all that really need to be in there?
I think it is good: When I'm coding, I find it easy enough to work from a service interface, to the implementation of the interface, to the dependencies of the implementation. This works for me when developing Tapestry itself, or writing apps in Tapestry. Since there are so many small objects, no single object is large, or complex, or hard to understand or debug. It's a bit daunting to know where to start, I'm sure. However, only a few of these services are all that relevant for day-to-day development of Tapestry.
The moral of the story is that simplicity is hard! In Tapestry, pages and templates are as simple and straight forward as I think is possible. There's no excess, no distractions, no clutter, no boilerplate. Much of the logic represented in the diagram is to "fill around the edges" of this simplicity, to bridge the gap from the simple Tapestry component model to the much more complex world of stateless HTTP and multi-threaded request handling.
I like seeing UML diagrams of real stuff. I wish there would be a mean to search for UML diagram related to certain projects.
ReplyDeleteLike a repository or some kind of markup or SVG thing ...
It gives a quick overview in a way that should be comparable amongst projects.
I appreciate.
Bruno
> It's a bit daunting to know where to start
ReplyDeleteNow that is the understatement of the year. :)
Edges in the dependency graph are their own form of complexity. Somewhere there is a happy medium of node size and edge count. But all projects, I think, have a certain amount of inherent complexity, and no amount of engineering will make that go away. You can shove it around on your plate but sooner or later you're going to have to eat your vegetables.
IMO, the way to handle this kind complexity is to introduce a hierarchical grouping construct such as modules, packages or subsystem. Then you can show dependencies between groups of nodes, reducing the clutter.
ReplyDeleteToo many nodes and edges in a single diagram make it useless (besides from demonstrating the complexity).
The question is what you want to do with the diagram. If it's for a tee-shirt or to show off how much Tapestry offers, your current layout is fine.
ReplyDeleteIf it's to help readers understand Tapestry, then I like Edwin's suggestion. I would add a legend for the colors and the lines (hash vs. solid).
I would also consider skipping the internal services, just to make it more readable.
Separately, though, I want to acknowledge just how much functionality you've included in Tapestry. Good stuff.