Stabilizing the Application Structure by Using Layer Diagrams

  • Article

When a team develops code in small increments, it changes and extends the code frequently. These changes can lead to increasingly complex dependencies, which make the code more difficult to change over time. Your team can use layer diagrams to design and validate the dependencies between components in your application to help prevent this problem.

Using a layer diagram, your team can view the major parts of the application and the dependencies between them, without the details of how the parts work and how they interact.

Your team can also use layer diagrams to make sure that the code conforms to the architecture. When you draw a layer diagram in Visual Studio, you can assign groups of classes from your code to each layer and specify the dependencies by using arrows. You can then use Visual Studio to validate that the dependencies in the code actually follow the arrows you have drawn in the layer diagram.

Your team can make sure that future changes always comply with the architecture by defining a check-in policy to validate the layer diagram and by using it in the continuous builds of your team.

Introduce layer validation

Your team can start to use layer validation by following the procedures outlined in this section.

To use layer validation when you are writing new code

  1. Near the time when you first write code for the application, draw a layer diagram to represent the major components and their dependencies. You will probably change the diagram during the project as the application develops.

    For more information, see Layer Diagrams: Reference.

  2. As you create namespaces or classes, assign them to layers.

  3. Before you check in code, right-click the layer diagram and then click Validate Architecture.

  4. Add layer validation to the check-in and regular build procedures.

    For more information, see How to: Validate .NET Code Against Layer Diagrams.

To introduce layer validation when you update an existing application

  1. Use Architecture Explorer and directed graphs to explore the application to gain some understanding of its structure. The following steps will help you improve your understanding.

  2. Describe the major components and dependencies should be. For more information, see How to: Create Layer Diagrams from Artifacts.

  3. Assign elements to layers by dragging them from Architecture Explorer or Solution Explorer.

  4. Right-click the layer diagram, and then click Validate Architecture.

  5. Inspect any error reports, and fix any errors by using the following approaches:

    • Fix the layer diagram. Improve the layer diagram to represent the existing code more accurately, or reassign code elements to different layers.

    • Fix the code. If you feel that your layer diagram represents a better design than the existing code, you might want to update the code so that it matches your layer diagram.

      For more information, see Refactoring existing code to conform to your layer diagram later in this topic.

  6. Repeat the previous steps until no errors are reported.

  7. Add layer validation to the check-in and regular build procedures.

    For more information, see How to: Validate .NET Code Against Layer Diagrams.

Refactor existing code to conform to your layer diagram

When your team starts to work on an existing application, it might find that the structure of the application is more complex than it has to be. You will notice this situation when you try to draw a layer diagram and assign elements to the layers. Your team might not be able to assign elements to layers in a way that can be validated without introducing layers and dependencies that are logically unnecessary or by introducing dependencies that skip layers or form loops. Shortcomings such as these make the code difficult to understand and change and can make its behavior seem inconsistent to users.

Your team can make the code easier to work on by refactoring it to improve its design. When your team decides to refactor the code to improve the design, consider the following points:

  • Keep the refactoring changes separate from other changes. A refactoring change should involve no important change in the user stories.

  • Add each proposed change to the product backlog, and include a description of the change and the expected benefit.

    Note

    Refactoring changes that require only hours to implement and test can be handled as bugs. Larger refactoring changes should be added to the product backlog and estimated and prioritized together with other items in the backlog.

  • Before you refactor, write tests that make sure that the functionality of the area that you are working on has not changed.

Updating the layer model

After the first one or two sprints, the layer diagrams should remain stable. Usually, a layer validation error should be considered an error in the code instead of an error in the layer model.

When you must update the layer model, review the proposed change with your team.

Most changes to the layer model fall into the following categories:

  • Extension. You are adding more components to the code and want to add layers to comply with them.

  • Refinement. Many code elements are currently assigned to a single layer. You want to improve the effectiveness of layer validation by separating the single layer into smaller layers.

  • Refactoring. You want to improve the dependency structures of the existing code. The existing structures are reflected in the current layer diagrams. You therefore want to improve the layer diagram and the code at the same time.