UML & Diagramming

  • Diagramming Tools – A (Biased) Survey

    Diagramming tools can help you to quickly understand a new project, debug code, visualize and enforce usage patterns, and quickly generate high quality documentation.  All good.  However, not all tools are created equal and there are lots of legacy tools (UML has been around for a while).  I wanted to take a look at what is out there to get a sense for how these tools are evolving.

    Below is a slice if you will through what are some next generation offerings in software development, tools that are trying to do something different, and some well established old-guard tools that everyone has heard of and compares all comers too.

    Code Canvas Example

    Debugger Canvas  Debugger Canvas by Microsoft (see video) is based on Code Canvas which was developed at Microsoft Research in  collaboration with the Code Bubbles folks from Brown.  Debugger Canvas is available to premium Microsoft Visual Studio license holders.  I love how you can view a GUI widget, its documentation, and implementation side by side in one clean view.  The development metaphor is very different from a traditional IDE.


  • I’ve Just Inherited an Application – Now What?

    Lucene Overview Diagram

    What if I had a diagram like this?

    I have previously written about how lack of decent software documentation can cause problems in doing what we developers love to do, deliver functioning software. Documentation, code comments and good variable naming are all key to understanding code.  This applies to both code that we write and applications that we use through their API’s.  We could just as easily be looking at C/C++/C#, Python, PHP or any language but for now let’s stay with Java (read more about advantages of Java over other languages at .

    I want to illustrate how useful diagrams are in understanding an existing complex Java code base. Understanding code quickly is particularly important when inheriting a new project or trying to figure out how to use a third party package or open source project. As we all know we are typically faced with tight deadlines, limited resources, and herculean objectives. Sound familiar?

  • Code Visibility: one factor of code quality that you shouldn’t forget

    Every developer cares about code quality. But how do you maintain code quality throughout the software development cycle? Readability, modularity, and efficiency all are important factors of writing good code but there isn’t much agreement on the best way to maintain a high level of code quality.

    One factor which is often missed in discussions is code visibility, or making sure your code has a clear structure so that others can easily understand it. (Take a look at the diagram above for some of the difficulties encountered when there is a lack of code visibility).

  • UML- Useless Meaningless Lousy?

    UML LOGOIt is easy to find numerous negative sentiments about UML. The main complaints seem to revolve around UML being of little practical use and inconvenient to draw and update.

    I have been looking into the practicality of UML and find this answer on stackoverflow very interesting:

    Using UML is like looking at your feet as you walk. It’s making conscious and explicit something that you can usually do unconsciously. Beginners need to think carefully about what they’re doing, but a professional programmer already knows what they’re doing. Most of the time, writing the code itself is quicker and more effective than writing about the code, because their programming intuition is tuned to the task.

    My question is: Is it all that bad to walk while looking at your feet? It is often said that learning to walk is one of the hardest skills a person has to learn. However, in time walking doesn’t seem like a “learned skill” anymore because we do it so much that it seems natural. But what happens when we are walking along a tricky path strewn with pebbles, banana-peels and the like; wouldn’t we feel safer to look at our feet as we walk?

  • From Java to Spring and Beyond – Making Diagrams (and UML) work for developers

    One of the strengths of working with Java is the large number of frameworks that are available. These frameworks are great for taking care of the basic tasks involved in building Java based apps. But they often bring about challenges in understanding - whether it is xml files or annotation based configurations, developers needing to work with these frameworks have to see how different parts of the code are connected. With this in mind we have extended Architexa to not just show code relationships but have also built special support for popular frameworks like Spring and Struts. We are happy to announce that we will be demoing this functionality at EclipseCon 2011 as part of the Hot New Products Showcase. We are pushing the edge here - so we are making this capability available as an 'early access' version. You can find it by default in all versions of the Architexa Suite. We would really like to hear what you think about it, and invite you to extend your trial of the product as we refine the implementation based on your feedback In this release we are including early access to a number of frameworks. With Spring we have added support for Dependency Injection and Web Flow. We have also added support for Struts (1 and 2) and Tiles. Spring Bean classes can be shown in both class and sequence diagrams along with any Property fields they contain. This allows for easy exploration of the hierarchy of beans along with a clearer view of dependency injection. Struts support enables you to explore the actions defined in xml configurations files; specifically, the dependencies to other actions, jsp pages, and classes all within an easy to understand class diagram. Tiles support allows you to easily see where different JSPs plug into various web components and how they relate to other java elements in a class diagram.
  • Understanding Code Visually: Three Ways that Work

    In trying to help developers understand code we have made sure to listen to what they have to say. We’ve noticed that many developers utilize UML style diagrams to try to understand code. However many problems exist with existing tools. I have tried using a number of UML tools and found that the reverse-engineering capabilities in the majority of them were not helpful for understanding tasks. They focus on designing tasks; reverse-engineering capabilities often just end up showing convoluted pictures and lots of useless information. Even developers that commonly use these tools ask us how to best understand code. Of course there are many solutions to this problem and the solution varies depending on the situation.

    It is important to think about which specific perspectives you need to understand. Is the structure of the codebase in a state of disrepair and needs attention? Or are underlying code concepts, features, and logic the most important? There seem to be three main types of diagrams people use to help visually understand code.

  • Better Architectural Documentation in 5 easy steps

    Documenting code can be a time consuming challenge, especially when dealing with unfamiliar spaghetti code. Diagrams and UML tools can help with this but what appears to be a comprehensive diagram to one person might actually result in more confusion to someone else. It’s important to maintain a clear idea of what concepts your diagram is conveying. I often find myself attempting to document entirely with inline comments. This is often very useful but presents challenges when documenting concepts that span multiple classes/methods. There are several tricks I’ve found that make the task of diagramming code significantly easier.

  • High Level Documentation: Layered or Package Diagrams?

    Layers or packages?Layered diagrams seem to have become an integral part of documenting code well, but many developers don’t realize that they aren’t technically included in the UML spec. The UML standard provides a different sort of high level concept: the Package Diagram. It is often not clear when one should be used over the other, but I will attempt to show the strengths and weaknesses of both.

    A layered diagram is useful for organizing and understanding the structure of a large code base from the top most level down. Instead  of using cumbersome directory trees or code searches to determine the relationships between packages, you can easily see them all in one space. Someone unfamiliar with the code base can easily examine a layered diagram and in a short time will have a grasp of the dependencies inherent in the project without having to be bogged down with details on classes or methods. It is also possible to include architectural components in a layered diagram, including databases, cloud/web components, and UIs. This allows for a flexible diagram that can show a great deal of information concisely.A project with a complex but easily understandable layered diagram is a sign of a well organized codebase.

  • A glimpse into the current state of UML use

    Just the other day I was sent a link to a recent survey conducted by Dwayne Anius and Brian Dobing on the topic "Programmer's views on the usefulness of UML diagrams"; a topic I am acutely interested in. In the survey approximately 100 developers responded providing information on their development experience and use of different UML diagrams.
  • Determining Which UML Diagram to Use

    There are many types of UML diagrams other than the commonly used class diagram. Choosing between them can be a challenge; which type should we useDiagram Collage and when? What diagram is right for my problem/codebase? We’ve seen that UML Diagrams are great for designing code but how can we make sure they remain useful when maintaining that same code? I spent some time thinking about these questions and here are some of the answers that I have come up with.

    Structure Diagrams

    One type of diagrams are the ‘structure diagrams’, they depict information without regard for temporal ordering. They can help to break large projects or features into parts and specify which parts do what and how they interact. The most common example, Class diagrams (example) are very useful, however there are many more underutilized structure diagrams that can help with specific tasks.

  • Why People Fail With UML Diagrams

    UML and UML tools seem to always be getting a lot ofUML LOGO bad press. This might be the result of developers not utilizing them for their intended purposes. As they were originally imagined, UML diagrams should only be used when designing code. They should not be used when sitting down to detangle a pile of incomprehensible logic or making sense of an alien design pattern; and especially not for generating all your project’s code. Experienced designers may already have come to this realization but for others some explanation is in order.

    There are a lot of options when it comes to UML diagrams. Other than the ever present Class Diagram there are: Structure Diagrams (class, deployment, package, etc), Behavior Diagrams (activity, usecase, etc), and Interaction Diagrams (communication, sequence, etc). They are all used to meet a very specific need; communicating design requirements from product management to the development team. This is very important when working with most software processes since they require all functionality to be determined during the design phase. Five months later when features are added/removed and code is re-factored, maintaining the UML diagrams becomes tedious and the diagrams are no longer helpful.