UML & Diagramming

Diagramming Tools – A (Biased) Survey

Posted in Agile & Development Methodologies, Design Patterns & Architecture, Developer Tools, Java, UML & Diagramming on September 21st, 2012 by Christopher Deschenes6 Comments

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.

 

read more »

 

I’ve Just Inherited an Application – Now What?

Posted in Developer Tools, Documentation & Communication, Java, UML & Diagramming on July 31st, 2012 by Christopher DeschenesBe the first to comment
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 theappsolutions.com .

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? read more »

 

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

Posted in Agile & Development Methodologies, Design Patterns & Architecture, Developer Tools, UML & Diagramming on July 13th, 2011 by xin Zhou2 Comments

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).
read more »

 

UML- Useless Meaningless Lousy?

Posted in UML & Diagramming on July 5th, 2011 by Novita Mayasari17 Comments

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? read more »

 

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

Posted in Developer Tools, Eclipse, Java, UML & Diagramming on March 21st, 2011 by Seth Rosen1 Comment
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
 

Understanding Code Visually: Three Ways that Work

Posted in Developer Tools, Documentation & Communication, UML & Diagramming on November 8th, 2010 by Seth Rosen19 Comments

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.

read more »

 

Better Architectural Documentation in 5 easy steps

Posted in Documentation & Communication, UML & Diagramming on November 4th, 2010 by Seth RosenBe the first to comment

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.

read more »

 

High Level Documentation: Layered or Package Diagrams?

Posted in UML & Diagramming on August 23rd, 2010 by Seth Rosen3 Comments

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.

read more »

 

A glimpse into the current state of UML use

Posted in UML & Diagramming on June 10th, 2010 by Seth RosenBe the first to comment

The percentage of responders that said that they have used this diagram type. Class, Sequence, and UseCase diagrams stand out as the most often used.

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. (you can add to this number by participating here) With millions of developers worldwide and only 100 represented in this survey it is difficult to get a general picture of the usefulness of UML but it is apparent from a cursory glance at the stats that Class Diagrams are the most widely utilized. This fits with the general consensus that class and sequence diagrams are the most preferred UML diagrams.

read more »

 

Determining Which UML Diagram to Use

Posted in UML & Diagramming on April 22nd, 2010 by Seth Rosen1 Comment

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.
read more »