Category: Software Craftsmanship

How to Organize your Code

Alexander von Zitzewitz 3 Comments

In this article I am going to present a realistic example that will show you how to organize your code and how to describe this organization using our architecture DSL (domain specific language) implemented by our static analysis tool Sonargraph-Architect. Let us assume we are building a micro-service that manages customers, products and orders. A high level architecture diagram would look like this:

System Architecture

It is always a good idea to cut your system along functionality, and here we can easily see three subsystems. In Java you would map those subsystems to packages, in other languages you might organize your subsystem into separate folders on your file system and use namespaces if they are available.

Read More

Automate Cross-Project Analysis

Ingmar Kellner Leave a comment

Sonargraph is our tool to quickly assess the quality of a project. I get frequently asked, how Sonargraph supports the Enterprise Architect who needs to answer quality-related questions in the broader context across several projects.
Since we recently released new functionality that allows the automation of re-occurring quality checks, it is now the right time to write a blog post.
Example questions that an enterprise architect wants to answer:

  1. How frequently does a certain anti-pattern occur?
  2. How strong is the dependency on deprecated functionality?
  3. How many of my projects suffer from high coupling?

This article will demonstrate the following core functionality of Sonargraph to answer the above questions for a couple of projects and how to automate this analysis.

  1. Use a script to detect an anti-pattern (“Supertype uses Subtype”)
  2. Create a simple reference architecture to detect usage of sun.misc.Unsafe
  3. Add a threshold for a coupling metric (NCCD)
  4. Export a quality model
  5. Use Sonargraph Build Maven integration to execute the analysis.
  6. Create a small Java project to execute the Sonargraph Maven goal, access the data in the generated XML reports and create a summary.

Read More

Meet the Sonargraph Gradle Plugin – and Say Goodbye to JDepend

Alexander von Zitzewitz 2 Comments

With the release of Sonargraph 8.8.0 today we also released the first version of our brand new Gradle plugin. It allows you to create reports for any Java project, even those that do not have a Sonargraph system specification. This is a quick and easy way to get some metrics and other findings like circular dependencies about your project. In this article I am going to show you, how you can use our Gradle plugin to make your build fail if your system contains cyclic package dependencies. Believe it or not, there are still people out there that use JDepend for this very reason (I did too, but that was more than a decade ago). Since you can do everything I am describing now with our free Sonargraph-Explorer license including the interactive visualization of cycles, I think you won’t regret saying “Good Bye” to JDepend and “Hello” to Sonargraph. Read More

Designing a DSL to Describe Software Architecture (Part 3)

Alexander von Zitzewitz 4 Comments

Connecting Complex Artifacts

After having covered the basics and some advanced concepts in the previous articles this post will examine the different possibilities to define connections between complex artifacts. Let us assume we use the following aspect to describe the inner structure of a business module:

// File layering.arc
exposed artifact UI 
{ 
    include "**/ui/**"
    connect to Business 
} 
exposed artifact Business 
{ 
    include "**/business/**"
 
    interface default
    {
        // Only classes in the "iface" package can be used from outside
        include "**/iface/*"
    }
 
    connect to Persistence
} 
artifact Persistence 
{ 
    include "**/persistence/**" 
}
exposed public artifact Model
{
    include "**/model/**"
}

This example also shows a special feature of our DSL. You can redefine the default interface if you want to restrict incoming dependencies to a subset of the elements assigned to an artifact. Our layer “Business” is now only accessible over the classes in the “iface” package. Read More

Designing a DSL to Describe Software Architecture (Part 1)

Alexander von Zitzewitz 7 Comments

Software architecture defines the different parts of a software system and how they relate to each other. Keeping a code base matching its architectural blueprint is crucial for keeping a complex piece of software maintainable over its lifetime. Sure, the architecture will evolve over time, but it is always better to have an architecture and enforce it than giving up on keeping your code organized. (See my recent blog post: Love your Architecture)

The problems start when it comes to describing your architecture in a formal and enforceable way. You could write a nice Wiki article to describe the architecture of your system, or describe it on a Powerpoint slide or with a set of UML diagrams; but that would be quite useless because it is not possible to check in an automated way whether or not your architecture is respected by the code. And everybody who ever worked on a non-trivial project with more than 2 developers knows that rules will be broken. That leads to an ever increasing accumulation of architectural debt with all kinds of undesirable side effects for the long term sustainability of a piece of software. You could also use Sonargraph 7 or similar tools to create a graphical representation of your architectural blueprint. That is already a lot better because you can actually enforce the rules in your automated builds or even directly in the IDE. But it also means that everybody who wants to understand the architecture will need the tool to see it. You also will not be able to modify the architecture without having access to the tool.

Wouldn’t it be nice if you could describe your architecture as code, if you had a DSL (domain specific language) that can be used by software architects to describe the architecture of a system and that is expressive and readable enough so that every developer is able to understand it? Well, it took us a while to come up with that idea, but now I believe that this is the missing puzzle piece to significantly boost the adoption of formalized and enforceable software architecture rules. The long term benefits of using them are just to good to be ignored.

Read More

Love your Architecture

Alexander von Zitzewitz 5 Comments

The single best thing you can do for the long term health, quality and maintainability of a non-trivial software system is to carefully manage and control the dependencies between its different elements and components by defining and enforcing an architectural blueprint over its lifetime. Unfortunately this is something that is rarely done in real projects. From assessing hundreds of software systems on three continents I know that about 90% of software systems are suffering from severe architectural erosion, i.e. there is not a lot of the original architectural structure left in them, and coupling and dependencies are totally out of control. Read More

Dead Code Detection

Ingmar Kellner Leave a comment

Research [Strei2014] and other sources (e.g. [Pizz2013]) have shown that typical software code bases contain 5-10% “dead code”, i.e. code that can be removed without reducing the functionality.
Streamlining the code base by identifying and removing dead code has several benefits:

  • Less maintenance cost: Whilst dead code is less likely to be changed frequently, it still has to be understood and might be effected by refactorings.
  • Smaller footprint: Less code makes the development environment faster, the build and deployment processes are more efficient, and the size of runtime artifacts are smaller.
  • Better precision for calculated metrics: Dead code contributes to software metrics, e.g. “average test coverage” might be improved by tests for unused code and therefore creating false confidence.

Dead code grows in projects for the following reasons:

  • Only few developers check in their IDE if some element is still in use, when they remove a reference to it.
  • Identifying reliably that a public class or method is “dead code” is not a trivial task and requires deep knowledge about the code base.
  • Removing seemingly dead code can easily lead to new bugs therefore developers are usually reluctant to remove them.

It is likely that more dead code exists in large and long running projects with a high fluctuation of developers.

Detecting dead code is a good use case to illustrate Sonargraph Explorer’s powerful scripting API and to demonstrate how it can be used to efficiently detect dead code within a Java project including public classes, methods and fields.

Read More

Identifying Dependencies for Breaking Cycles

Dietmar Menges 2 Comments

Dependency cycles in software systems have very negative impact on characteristics like testability, understandability and reuse (as explained here). Cycles with only a few nodes (say 5 to 10) might be resolveable quite simply by manually analyzing them. For bigger cycles it is helpful to have an automated analysis at hand based on an algorithm solving the minimum feedback arc set problem. A feedback arc set of a directed graph is a subset of its arcs that upon removal would transform a cyclic into an acyclic directed graph. Such an algorithm combined with user input about the domain (i.e. which dependencies are absolutely necessary and which absolutely violate design decisions) is able to deliver excellent results. Read More

The Importance of Defining “Done” Correctly

Alexander von Zitzewitz Leave a comment

The nicest thing you can say to a project manager or your boss is something like “I am done with my task / project“. Everybody loves people who are getting things done. If you do that consistently you will get rewarded and used as an example for those other slackers who are having a bit more trouble with getting things done. On the other hand people who write beautiful, elegant and maintainable code hardly ever get any recognition for that. Nobody really seems to care about the “internals” as long as the software somehow does what it is supposed to do. In a cultural environment like this technical quality, code maintainability and sustainability in general are easily thrown under the bus. Read More