Socomo - care about the composition of your java code
Socomo is a simple tool to visualize the composition of your source code and track changes to the composition as you progress with the development of your java project. You can use this tool to:
- Explain internal design of your modules by showing the diagram of component dependencies.
- Assure that architecture of your project is not being broken by seeing what new dependencies are added.
- Brag on your blog or twitter how great the structure of your code is, proving it with the diagrams.
See Socomo in action on the Guava project:
Try it now on your code! For a project build with maven do this:
Alternatively, for a jar file, download the latest release and do this:
java -jar socomo-standalone.jar -d path/to/your.jar
Either of the above commands generates the
socomo.html file and opens it in the browser.
You'll be presented with an interactive visualization of the structure of the code.
To track changes to the composition commit the
socomo.html file to your source code repository
and add socomo maven plugin to your project. Whenever composition changes
the plugin updates this human-readable file, so you'll have a history of changes in the most
convenient place - in your source code repository.
How to Read Diagrams
The diagram shows composition of your code at some specific level, typically the topmost package of the project. Each subpackage at this level is a component represented as node in the diagram. Components are arranged on the diagram to form layers: a component uses other components that are below it, and is used by components that are above it.
The actual dependencies analyzed from the bytecode are represented as edges. The wider the edge, the stronger is the dependency between components.
When you select a component, blue edges show outgoing dependencies pointing to components used by the selected one, and brown edges show incoming dependencies from the components that use the selected one. Red edges are dependencies that point upwards, against the layers, and thus are the cause of a cyclic dependency between two or more components.
Best Practices for Composition
Socomo is an opinionated tool that requires you to structure the code in the right way to be most useful:
Make your topmost components speak about the business. They shouldn't tell which frameworks do you use. The technical details are more familiar to a developer and thus less important than the business domain.
Keep your dependencies acyclic. If two components depend on each other, you cannot understand and work on them one at a time, they actually form one larger component.
Let your components be balanced in size. Having one huge component amongst tens of smaller ones defies the whole purpose of dividing the code.
Those principles will help you avoid your project being a big ball of mud.
Socomo Maven Plugin
Add following snippet to the
<build><plugins> section in your
pom.xml file. For multi-module projects,
you can add it just to the parent pom, so that it is inherited by all modules.
<plugin> <groupId>pl.gdela</groupId> <artifactId>socomo-maven</artifactId> <executions> <execution> <goals> <goal>analyze</goal> </goals> <configuration> <level>com.example.myproject</level> </configuration> </execution> </executions> </plugin>
level property is optional, if not given it will be guessed. The plugin should be bound to a phase
that is executed after your code has been compiled, so by default it is bound to the
Download the latest release and do this to get help how to use it:
java -jar socomo-standalone-*.jar --help
mvn installto install a snapshot version of Socomo in your local maven repository.
- Use socomo maven plugin with the snapshot version
or socomo standalone from
socomo-core/targetdirectory to produce a
- Optionally you can use the
catfood.shscripts that perform both of the above at once.
npm --prefix socomo-view run serveto start serving
- Open the generated
socomo.htmlfile in the browser. Assets can be developed in-place, the browser will automatically reload them.
Socomo is designed for simplicity and ease of use. If you would like to dig deeper into your code structure or enforce some rules about dependencies, consider alternatives listed below.
Stan4J - simplest one to use, allows you to dig deeper into your code structure and analyze dependencies in detail.
Structure101 - comprehensive toolset to explore structure of your code, analyze dependencies between code elements, define desired architecture of the code, integrate with build systems to detect violations and track structure changes.
Lattix - similar to the above, but focused on visualization using dependency structure matrix instead of graph diagrams.
Most of the above have plugins for SonarQube, a widely used "Continous Inspection" system. They can also be used from within IntelliJ/Eclipse, though having a standalone GUI for visualizing software structure feels more ergonomic.