Uml As Notes

Yesterday I was poking around a code base, looking at the domain model part of the code. When exploring a code base, I like to take notes to help me remember what I'm learning. For some code bases, in particular domain models, I find it handy to sketch UML class diagrams.

UML has got rather out of fashion it seems. Although this isn't good for me financially, I can't say I'm displeased to see a lot of rather dodgy UMLisms going away. I continue to find it a useful tool, as I did that morning. As I worked my way around the code I would jot down classes and relationships, to see how the various classes played together.

I don't use “reverse-engineering” tools for this. Such tools run on your code base and automatically generate the class diagram. Although this is quite straight-forward to do technically, the result is rather useless. For me the value of a good diagram is that it highlights the important stuff, and ignores what's not. So I don't draw every class, let alone every relationship and feature. I decide to jot down things that I think are important to remember, particularly focusing on connections that often don't show up so much when you're looking at the code. I also only use a little of the endless class diagram syntax, and I'm not afraid of being sloppy with it. 1

When I'm doing this speed is important. Currently my favorite tool for this kind of jotting is Umlet 2. What I like about it is that most of what you capture goes in as text, using a wiki-ish markup. As a result I can quickly slap things in there, using the mouse just to broadly move things around as needed. It's a java program, so it suffers ugliness for availability.

When I'm doing this, I do the diagrams just for me; so I don't put effort into making them nice and clear for others. If I were to produce diagrams to help explain the code to others, I'd approach them differently. With notes I'm creating reminders for myself, with explanatory diagrams I'm trying to communicate different things to another audience. 3