A fully "structured" containment model is one where none of the containers contain more than a "mind-sized chunk" of child items, and none of the containers are cyclically dependent. Such a structure is dramatically less complex (easier to understand and develop) than the common "Big Ball of Mud (BBOM)" structure where "everything uses everything". There are plenty of other considerations in the construction of a modular architecture, but this is such a strong, measurable, achievable goal that we have provided the Structural over-complexity viewer on the left of the Model tab.

The viewer comprises an over-complexity chart which measures "the % of the code-base that lies within a Fat item" on one axis, and "the % of the code-base that lies within a Tangled region" on the other. 2 lists of the items that contribute to these 2 measures are included under the chart:

The chart tracks the over-complexity with each action you perform on the model - the first (large black) dot is the state of the package and/or module/project/JAR code-base structure that you specified in the project settings. The last (blue) dot indicates the structure of the current model after any model initialization and actions you have applied. Each time you make a change (create an action) to the model, a new dot is added to the chart.

Driving that blue dot down to the origin is a great guide while organizing your code into a well-structured containment model.

Plotting both values on the same chart is important. It is easy to remove cyclic dependencies between containers by merging those containers. But only if the resulting container is still below the Fat threshold will the over-complexity really be reduced. Likewise dividing a Fat container into several smaller containers can reduce the %Fat, but if the new containers are tangled, the codebase is not really any easier to understand.

The lists contain the items that are either Fat or Tangled. You can find these items in the LSM by clicking them in the list. This will expand the LSM as necessary to expose and select the item. It is actually the contents of the item that cause it to appear on the list, so you generally want to double-click to expand it and see inside. There you will either see a large sub-map of child items (Fat) or some child packages or module/project/JARs that are cyclically dependent.

Note that if a tangle is contained within a tangled parent, the child Tangle will not contribute to the overall %Tangled since all the code in the parent tangle is already counted. For example if a package is in a tangle, then the amount of code contained by the tangle is measured as a percentage of the total amount of code in the codebase to derive the %Tangled measure. If any sub-packages within the tangled package become tangled, or cease to be tangled, the %Tangled for the codebase will be unchanged. If the higher level package tangle is reorganized so that it is no longer tangled, then any lower level tangles will start to have a bearing on the %Tangled value. The same applies to nested Fat items.

Note:

• There may be more than one set of cyclically dependent child items (tangles) within a single tangled parent.
• You can spot tangles by the existence of feedback (upward) dependencies. You can ensure these are always displayed from the viewing options.
• You can organize cyclically dependent sets of items (tangles) into logical groups within the LSM using the viewing options.
• You can automatically organized the child items within a very fat item into "cohesive clusters" from the viewing options.
• When there are a lot of actions on the model, not every action is represented on the chart, each dot shows the effect of several consecutive actions.
• The %Fat and %Tangled measures are a bit different from the XS metrics in the Complexity perspective on the Views tab. We have found that these % measures are more suited as a measure of restructuring progress, whereas the XS framework used in the Complexity perspective is a more nuanced measure of the relative severity of a complexity problem.