I love reading code.
For two reasons :
If the code is bad, it is an awesome ego boost PLUS you get to foul mouth someone who has a good reputation for designing amazing things.
If the code is good, then you get to learn some new tricks and some cool patterns yet to be published anywhere
I am sure you read a lot of code and I am sure you’ll love this awesome code reading tool which I came across a few days ago - Architexa. Architexa also has collaborative documentation support, as I could clearly see with their codemaps project, but I’ve been using primarily for code reading.
Hey, forgot to tell you - Architexa is absolutely free for individual users.
Before going any further, a WOW video is here
A UML diagram is worth a thousand lines of code :
Architexa does not bring in a lot of diagrams but only the most relevant.
- Class diagram - for Static view
- Sequence diagram - for Dynamic view
- Layered diagram (package diagram + awesomeness) - for overall project static view
Class first - Class diagrams :
Imagine you are assigned to a new project or you are simply opening up an open source library to check its implementation.
If you are like me, you would probably
- go directly to the class that you are interested and start from there
- check all the methods of the class in the Outline window
- go to the method of choice and start drawing a Class dependency graph on your mind using the caller and the callee hierarchy.
With Architexa, all you need to do is to throw all your classes into a diagram. Inheritence hierarchy gets automatically mapped by default.
If you would like to map the associations (which I always do), then all you need to do is a right click.
You get to choose what associates/members you would want to display in your diagram
The best part I like about Architexa is that you could add/remove items that are not of interest to you. No more noisy A3 print outs.
The big picture - Layered diagrams
If you dont have any Class of interest, then you would probably do a package scan - you simply open up all packages and check how the files in the project are arranged. Again, you are trying to construct a Package Dependency graph and identify commonly used design patterns or frameworks. From my personal experience, I always found that idenfifying package dependency is more difficult than individual classes. However, Architexa does it naturally.
The following is a layered representation of a Google web toolkit project where the client and the server folder are dependent on the shared package (for models, of course). The white components indicate that they are siblings.
Say 1,2,3 - Sequence diagrams
I love the way that the messages are marked with not only its name but also the complete parameter list. And I absolutely love the way that the classes are marked with either a “C” (for class with source), “I” and “E” for interfaces and enums and a “jar icon” if the class is sourced from a bundle. Generics support in messages. FTW !!
No more lonely notes
The best part is that the diagrams does not live in isolation. You could just double click on your class component in your diagram and go to the respective class, or double click on your sequence message and go to that method in the code directly. This helps in switching back and forth between code and diagram (Ctrl+F6). Cool huh?
Optionally, you could export your diagram and have a hard copy printed out for reference - in case you hate switching windows.
A little disappointment when you are writing in language other than Java. Architexa currently supports only Java. And it is a plugin only for Eclipse. You might want to check with them for support for your other favourite IDEs. Mine is eclipse. I am good.
Referenced constants being a part of the sequence diagrams when you select the “Add All” references is strange but probably would come in handy. You can always remove the Constants files off the sequences, if you dont like them.
I see that the time taken to draw the diagram is stunning and the UI too looks light-weight. It takes no lag to drag and drop a class or remove a component off the diagram. I am running a 16GB + quad core though (show off time !!). YMMV
You could export the diagram as an image in your local file or in their community server (publicly available). However, I understand that if you need to have your own private secured server setup in your intranet you might want to go for an upgraded edition.
No support of Generics on the class diagram could be painful for some but I am not deeply concerned there.