High Level Documentation: Layered or Package Diagrams?


Monday, August 23rd, 2010 - By Seth Rosen

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.

Layered Diagram

Here we see a Layered Diagram showing the architecture and relationship of multiple packages by grouping them in layers

However not all layered diagrams are created equal. Small projects do not have much use for layered diagrams since the dependencies involved are often immediately obvious. Other projects where packages are poorly named or organized in an unintuitive way will have equally uninformative diagrams. (Although these diagrams might still be less confusing than studying the codebase to determine what is going on). Layered diagrams also do not provide the fine grain detail needed when working on a specific feature or class.

Overall, a properly created layered diagram is a tool most useful for understanding large code bases and finding hidden dependencies and should not be relied on too heavily when looking at the details of a project.

While layered diagrams group packages based on various abstractions and hierarchies, package diagrams show a high level view of a project by displaying named file folder icons connected by lines representing dependencies between packages. This may at first seem much less powerful but package diagrams can be adapted to highlight the structure of many different types of elements such as classes, use cases, and data entities.

Incorporating packages and package diagrams with other diagram types can allow you to describe a process from a higher level and simplify your diagrams. For example creating a use case diagram for a complex highly interactive project with many components can become overwhelming and convoluted. Grouping similar use cases into logical packages can make the diagram more accessible and provide a possible starting point for organizing your code base.

Large projects may need a detailed organizational plan. Package diagrams are perfect for this task. Using each package to represent groups of sub-packages allows a software architect to model the package structure with great detail and understand exactly how packages depend on each other. Layered diagrams are often also used for this task. In this case using both types in conjunction can help to illuminate problem areas.

Package Diagram

Here is a package diagram highlighting the high level relationships and usecases between different packages in a medical/search project.

In general, layered diagrams are best used when showing the conceptual structure of the package hierarchy quickly and concisely. Package diagrams are best used when grouping other UML diagrams and showing their relationships to the overall package structure. Both are well suited to organizing and designing a large codebase especially when working in an agile environment where architectural changes are an inevitability.

 

3 Comments

  1. I can recommend using javadoc extensions like umlgraph, apiviz or yDoc for generating javadocs with UML. Example : http://cia.sourceforge.net/legacy/apidocs/index.html (takes care of package diagram).

    For layering details and a general quality assesment, I am using Xradar which forces you to define layers and groupings of package structures. Example http://cia.sourceforge.net/legacy/xradar/index.html ..

    Since both the tools are easy to integrate in the build process, it removes the architects from the ivory tower.

    • Vineet Sinha says:

      Peter, I definitely like tools that provide diagrams from the code, and thanks for the tool recommendations – they are great starting points.

      But the problem is that automated diagrams end up not being really useful as is. It is often the human corrections and improvements to such automated diagrams that can actually make the documentation really useful.

      • I agree with you, that’s why I like to use xradar as a complement to generated diagrams. Always nice with some visualisation of projects, but should be used to get better info on howto refactor the code.

Leave a Reply