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.

Transcript

1. Simon Brown @simonbrown Visualise, document and explore your software architecture
9. Low detail
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
20. Visualise
32. The diagram isn’t self-evident, but we’ll explain it
33. Team 1 Team 1 Team 2 Team 2
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)
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
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
78. Any general purpose diagramming tool can be used to create software architecture diagrams
80. Do building architects use Microsoft Visio?
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
88. What is a “component”?
89. An auto-generated UML class diagram
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();
110. Navigate from diagram to source code
111. Diagrams are maps
114. Creating the model as code provides opportunities…
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"));
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…
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