Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Simon Brown: Visualize, Document, and Explore Your Software Architecture

1fa9cb8c7997c8c4d3d251fb5e41f749?s=47 Realm
November 25, 2016

Simon Brown: Visualize, Document, and Explore Your Software Architecture

Bio:
Simon lives in Jersey (the largest of the Channel Islands) and works as an independent consultant, helping teams to build better software. His client list spans over 20 countries and includes organisations ranging from small technology startups through to global household names. Simon is an award-winning speaker and the author of Software Architecture for Developers - a developer-friendly guide to software architecture, technical leadership and the balance with agility. He still codes too.
Abstract:
We value working software over comprehensive documentation" is what the manifesto for agile software development says, with the typical misinterpretation of these few words being "don't write documentation". Of course, that's not what the manifesto says and "no documentation" certainly wasn't the intent. It seems that many software teams have lost the ability to communicate what it is they are building and it's no surprise that these same teams often seem to lack technical leadership, direction and consistency. This session will look at various approaches and tools that you can use to visualise, document and explore your software architecture in order to build a better team.

1fa9cb8c7997c8c4d3d251fb5e41f749?s=128

Realm

November 25, 2016
Tweet

Transcript

  1. Simon Brown @simonbrown Visualise, document and explore your software architecture

  2. None
  3. None
  4. None
  5. None
  6. None
  7. None
  8. None
  9. Low detail

  10. None
  11. None
  12. Points of interest (e.g. districts and areas rather than every

    building on every street)
  13. High detail

  14. Selected highlights

  15. Elizabeth Castle Jersey

  16. Granite and concrete?

  17. History

  18. Maps Sights and itineraries History and culture Practical information

  19. None
  20. Visualise

  21. None
  22. None
  23. None
  24. None
  25. None
  26. None
  27. None
  28. None
  29. None
  30. None
  31. None
  32. The diagram isn’t self-evident, but we’ll explain it

  33. Team 1 Team 1 Team 2 Team 2

  34. None
  35. None
  36. What’s been challenging about the exercise?

  37. Who here uses UML on a regular basis?

  38. 1 out of 10 people use UML (in my experience)

  39. I do use UML (activity, class, sequence, collaboration, state)

  40. None
  41. None
  42. In my experience, software teams aren’t able to effectively visualise

    the software architecture of their systems
  43. We can visualise our process... ...but not our software!

  44. Moving fast in the same direction requires good communication

  45. Some notation tips… Titles Short and meaningful, numbered if diagram

    order is important Lines Favour unidirectional arrows, add descriptive text to provide additional information Layout Sticky notes and index cards make a great substitute for drawn boxes, especially early on Labels Be wary of using acronyms, especially those related to the business/domain that you work in Colour Ensure that colour coding is made explicit; watch out for colour-blindness and black/white printers Orientation Most important thing in the middle; be consistent across diagrams Shapes Don’t assume that people will understand what different shapes are being used for Keys Explain shapes, lines, colours, borders, acronyms, etc Responsibilities Adding responsibilities to boxes can provide a nice “at a glance” view (Miller’s Law; 7±2)
  46. Adding more text gives a nice “at a glance” view.

  47. It’s usually difficult to show the entire design on a

    single diagram Different views of the design can be used to manage complexity and highlight different aspects of the solution
  48. Why is there a separation between the logical and development

    views?
  49. “ …the architecture diagrams don’t match the code

  50. “the model-code gap”

  51. Do the diagrams reflect the code?

  52. As an industry, we lack a common vocabulary with which

    to think about, describe and communicate software architecture
  53. None
  54. Floor plans

  55. Circuit diagrams (pictorial or schematic)

  56. http://agilemodeling.com/artifacts/componentDiagram.htm

  57. Component? Relational Database Web Application LoggingComponent

  58. Ubiquitous language

  59. A common set of abstractions is more important than a

    common notation
  60. The abstractions must reflect the technology

  61. A software system is made up of one or more

    containers, each of which contains one or more components, which in turn are implemented by one or more classes. Class Class Class Component Component Component Container (e.g. web application, application server, standalone application, browser, database, file system, etc) Cont (e.g. web application, applicatio browser, databas ainer server, standalone application, file system, etc) Software System
  62. Static model (software systems, containers, components and classes) Runtime and

    behaviour (sequence and collaboration diagrams of elements in the static model) Deployment (mapping of containers to infrastructure) Business process and workflow Infrastructure (physical, virtual, containerised hardware; firewalls, routers, etc) Data (entity relationship diagrams) etc…
  63. The C4 model Classes (or Code) Component implementation details System

    Context The system plus users and system dependencies Containers The overall shape of the architecture and technology choices Components Components and their interactions within a container
  64. techtribes.je

  65. Component diagram (level 3) Container diagram (level 2) Context diagram

    (level 1) Class diagram (level 4)
  66. Component diagram (level 3) Container diagram (level 2) Context diagram

    (level 1) Class diagram (level 4)
  67. Component diagram (level 3) Container diagram (level 2) Context diagram

    (level 1) Class diagram (level 4)
  68. Component diagram (level 3) Container diagram (level 2) Context diagram

    (level 1) Class diagram (level 4)
  69. Diagrams are maps that help a team navigate a complex

    codebase
  70. Think about the target audience Business Operations Developers

  71. A simple notation (whiteboard and sticky note friendly, supplemented with

    colour coding) techtribes.je [Software System] techtribes.je is the only way to keep up to date with the IT, tech and digital sector in Jersey and Guernsey, Channel Islands. Anonymous User [Person] Anybody on the web. Twitter Connector [Component: Spring Bean + Twitter4j] Retrieves profile information and tweets (using the REST and Streaming APIs). Web Application [Container: Apache Tomcat 7.x] Allows users to view people, tribes, content, events, jobs, etc from the local tech, digital and IT sector.
  72. Shapes and colour can add an additional layer of information

  73. C4++ Enterprise context User interface mockups and wireframes Domain model

    Sequence and collaboration diagrams Business process and workflow models Infrastructure model Deployment model ...
  74. 4+1 architectural view model Philippe Kruchten Software Systems Architecture Working

    with Stakeholders Using Viewpoints and Perspectives (2nd Edition) Nick Rozanski and Eoin Woods
  75. C4 is not a design process

  76. Up front design vs retrospectively drawing diagrams

  77. None
  78. Any general purpose diagramming tool can be used to create

    software architecture diagrams
  79. None
  80. Do building architects use Microsoft Visio?

  81. None
  82. None
  83. Sketches get out of date, so why not auto-generate the

    diagrams?
  84. An on-premise API for Structurizr

  85. An auto-generated UML class diagram

  86. Diagramming tools see code rather than components

  87. None
  88. What is a “component”?

  89. An auto-generated UML class diagram

  90. None
  91. The code is the embodiment of the architecture

  92. Is the architecture in the code?

  93. Context Software Systems Integration points, APIs, known libraries, credentials for

    inbound consumers, etc. Containers IDE projects/modules, build output (code and infrastructure), etc. People Security groups/roles in configuration files, etc. Components Extractable from the code if an architecturally-evident coding style has been adopted.
  94. Containers Software Systems Integration points, APIs, known libraries, credentials for

    inbound consumers, etc. Containers IDE projects/modules, build output (code and infrastructure), etc. People Security groups/roles in configuration files, etc. Components Extractable from the code if an architecturally-evident coding style has been adopted.
  95. Components Software Systems Integration points, APIs, known libraries, credentials for

    inbound consumers, etc. Containers IDE projects/modules, build output (code and infrastructure), etc. People Security groups/roles in configuration files, etc. Components Extractable from the code if an architecturally-evident coding style has been adopted.
  96. “architecturally-evident coding style”

  97. Architecturally-evident coding styles include: Annotations/attributes (@Component, [Component], etc) Naming conventions

    (*Service) Namespacing/packaging (com.mycompany.system.components.*) Maven modules, OSGi modules, Java 9 and Jigsaw, JavaScript module patterns, ECMAScript 6 modules, microservices, etc
  98. Extract as much of the software architecture from the code

    as possible, and supplement where necessary
  99. Architecture description languages

  100. Create an architecture description language using code

  101. Structurizr for Java Structurizr for .NET

  102. // software systems and people Person softwareDeveloper = model.addPerson(Location.Internal, "Software

    Developer", "A software developer." ); SoftwareSystem structurizr = model.addSoftwareSystem(Location.External, "Structurizr", "Visualise, document and explore your software architecture." ); SoftwareSystem structurizrApi = model.addSoftwareSystem( Location.Internal, "Structurizr API", "A simple implementation of the Structurizr API, which is designed to be run on-premises to support Structurizr's on-premises API feature.” ); softwareDeveloper.uses(structurizr, "Uses"); structurizr.uses(structurizrApi, "Gets and puts workspace data using”); // system context view SystemContextView contextView = views.createSystemContextView( structurizrApi, "Context", "The system context for the Structurizr API." ); contextView.addAllElements();
  103. // software systems and people Person softwareDeveloper = model.addPerson(Location.Internal, "Software

    Developer", "A software developer." ); SoftwareSystem structurizr = model.addSoftwareSystem(Location.External, "Structurizr", "Visualise, document and explore your software architecture." ); SoftwareSystem structurizrApi = model.addSoftwareSystem( Location.Internal, "Structurizr API", "A simple implementation of the Structurizr API, which is designed to be run on-premises to support Structurizr's on-premises API feature.” ); softwareDeveloper.uses(structurizr, "Uses"); structurizr.uses(structurizrApi, "Gets and puts workspace data using”); // system context view SystemContextView contextView = views.createSystemContextView( structurizrApi, "Context", "The system context for the Structurizr API." ); contextView.addAllElements();
  104. // containers Container apiApplication = structurizrApi.addContainer( "API Application", "A simple

    implementation of the Structurizr API, which is designed to be run on-premises to support Structurizr's on-premises API feature.", "Java EE web application" ); Container fileSystem = structurizrApi.addContainer("File System", "Stores workspace data.", ""); structurizr.uses(apiApplication, "Gets and puts workspaces using"); apiApplication.uses(fileSystem, "Stores information on"); // container view ContainerView containerView = views.createContainerView(structurizrApi, "Containers", "The containers that make up the Structurizr API." ); containerView.addAllElements();
  105. // containers Container apiApplication = structurizrApi.addContainer( "API Application", "A simple

    implementation of the Structurizr API, which is designed to be run on-premises to support Structurizr's on-premises API feature.", "Java EE web application" ); Container fileSystem = structurizrApi.addContainer("File System", "Stores workspace data.", ""); structurizr.uses(apiApplication, "Gets and puts workspaces using"); apiApplication.uses(fileSystem, "Stores information on"); // container view ContainerView containerView = views.createContainerView(structurizrApi, "Containers", "The containers that make up the Structurizr API." ); containerView.addAllElements();
  106. “Component Finder” with pluggable strategies, implemented using reflection & static

    analysis (e.g. Java Annotations, .NET Attributes, type name ends with “Controller”, type extends class X, type implements interface Y, supplement model with type-level comments from source code, etc)
  107. // components ComponentFinder componentFinder = new ComponentFinder( apiApplication, "com.structurizr.onpremisesapi", new

    TypeBasedComponentFinderStrategy( new NameSuffixTypeMatcher("Servlet", "", "Java Servlet") ), new StructurizrAnnotationsComponentFinderStrategy(), new SourceCodeComponentFinderStrategy(new File("../src"), 150)); componentFinder.findComponents(); structurizr.uses( apiApplication.getComponentWithName("ApiServlet"), "Gets and puts workspaces using", "JSON/HTTPS" ); // component view for the API Application container ComponentView componentView = views.createComponentView(apiApplication, "Components", "The components within the API Server." ); componentView.addAllElements();
  108. // components ComponentFinder componentFinder = new ComponentFinder( apiApplication, "com.structurizr.onpremisesapi", new

    TypeBasedComponentFinderStrategy(), new StructurizrAnnotationsComponentFinderStrategy(), new SourceCodeComponentFinderStrategy(new File("../src"), 150)); componentFinder.findComponents(); structurizr.uses(apiApplication.getComponentWithName("ApiServlet"), "Gets and puts workspaces using", "JSON/HTTPS"); // component view for the API Application container ComponentView componentView = views.createComponentView(apiApplication, "Components", "The components within the API Server." ); componentView.addAllElements();
  109. None
  110. Navigate from diagram to source code

  111. Diagrams are maps

  112. None
  113. None
  114. Creating the model as code provides opportunities…

  115. None
  116. Build pipeline integration keeps software architecture models up-to-date

  117. Document

  118. “ Working software over comprehensive documentation Manifesto for Agile Software

    Development, 2001
  119. There are many libraries in the middle-tier; are they components?

    It looks like there are multiple architectural layers. There’s a web application. There are some WCF service references. Lots of C# code!
  120. The code doesn’t tell the whole story

  121. Tribal knowledge “just talk!” “diagrams and documents are just props

    for conversations”
  122. The bus factor (it’s not just about buses though!) Do

    you know how X works? No idea what you’re talking about...
  123. Software Architecture Document 1. A summary of the context and

    architectural drivers (requirements, constraints and principles) 2. A high-level description of the software architecture and the rationale (containers, components, etc) 3. A high-level description of the deployment and operational concerns
  124. Software Architecture Document Guidebook Maps Sights and itineraries History and

    culture Practical information
  125. Documentation should describe what the code doesn’t

  126. How much of the document is up to date and

    relevant?
  127. The software guidebook is living and evolving

  128. Product vs project

  129. Microsoft Word?

  130. // documentation File documentationRoot = new File(“.”); Documentation documentation =

    workspace.getDocumentation(); documentation.addImages(documentationRoot); documentation.add(structurizrApi, Type.Context, Format.Markdown, new File(documentationRoot, "context.md")); documentation.add(structurizrApi, Type.Data, Format.Markdown, new File(documentationRoot, "data.md")); documentation.add(structurizrApi, Type.Containers, Format.Markdown, new File(documentationRoot, "containers.md") ); documentation.add(apiApplication, Format.Markdown, new File(documentationRoot, "components.md")); documentation.add(structurizrApi, Type.DevelopmentEnvironment, Format.Markdown, new File(documentationRoot, "development-environment.md") ); documentation.add(structurizrApi, Type.Deployment, Format.Markdown, new File(documentationRoot, "deployment.md") ); documentation.add(structurizrApi, Type.Usage, Format.Markdown, new File(documentationRoot, "usage.md"));
  131. // documentation File documentationRoot = new File(“.”); Documentation documentation =

    workspace.getDocumentation(); documentation.addImages(documentationRoot); documentation.add(structurizrApi, Type.Context, Format.Markdown, new File(documentationRoot, "context.md")); documentation.add(structurizrApi, Type.Data, Format.Markdown, new File(documentationRoot, "data.md")); documentation.add(structurizrApi, Type.Containers, Format.Markdown, new File(documentationRoot, "containers.md") ); documentation.add(apiApplication, Format.Markdown, new File(documentationRoot, "components.md")); documentation.add(structurizrApi, Type.DevelopmentEnvironment, Format.Markdown, new File(documentationRoot, "development-environment.md") ); documentation.add(structurizrApi, Type.Deployment, Format.Markdown, new File(documentationRoot, "deployment.md") ); documentation.add(structurizrApi, Type.Usage, Format.Markdown, new File(documentationRoot, "usage.md"));
  132. None
  133. How long? (something I can read in 1-2 hours, with

    a coffee, to get a good starting point to jump into the code)
  134. Explore

  135. Once you have a model, you can explore it…

  136. None
  137. None
  138. None
  139. None
  140. None
  141. None
  142. Summary

  143. Virtual Panel on Software Architecture Documentation (2009) http://www.infoq.com/articles/virtual-panel-arch-documentation

  144. Diagrams are maps that help a team navigate a complex

    codebase
  145. Documentation should describe what the code doesn’t

  146. The 1990’s called and they want their tools back. It’s

    2016 … we shouldn’t be using a general purpose diagramming tool (Visio, OmniGraffle, Gliffy, draw.io, etc) for software architecture!
  147. Do you have a ubiquitous language to describe your software?

    simon.brown@codingthearchitecture.com @simonbrown on Twitter
  148. For more information… https://leanpub.com/visualising-software-architecture