Software Architecture for Developers (Simon Brown) (Z-Library)

Software Architecture for Developers Technical leadership by coding, coaching, collaboration, architecture sketching and just enough up front design Simon Brown This book is for sale at http://leanpub.com/software-architecture-for-developers This version was published on 2015-09-12 This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. ©2012 - 2015 Simon Brown

Tweet This Book! Please help Simon Brown by spreading the word about this book on Twitter! The suggested hashtag for this book is #sa4d. Find out what other people are saying about the book by clicking on this link to search for this hashtag on Twitter: https://twitter.com/search?q=#sa4d

For Kirstie, Matthew and Oliver

Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Software architecture has a bad reputation . . . . . . . . . . . . . . . . . . . . . i Agile aspirations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii So you think you’re an architect? . . . . . . . . . . . . . . . . . . . . . . . . . . . ii The frustrated architect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii About the book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Why did I write the book? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv A new approach to software development? . . . . . . . . . . . . . . . . . . . . . v Five things every developer should know about software architecture . . . . . . . vi About the author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Software architecture training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi I What is software architecture? . . . . . . . . . . . . . . . . 1 1. What is architecture? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 As a noun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 As a verb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Types of architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 What do they all have in common? . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. What is software architecture? . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 System architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

CONTENTS Software architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Enterprise architecture - strategy rather than code . . . . . . . . . . . . . . . . . 8 4. Architecture vs design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Making a distinction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Understanding significance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. Is software architecture important? . . . . . . . . . . . . . . . . . . . . . . . . 12 A lack of software architecture causes problems . . . . . . . . . . . . . . . . . . . 12 The benefits of software architecture . . . . . . . . . . . . . . . . . . . . . . . . . 13 Does every software project need software architecture? . . . . . . . . . . . . . . 13 6. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 II The software architecture role . . . . . . . . . . . . . . . . 15 7. The software architecture role . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1. Architectural Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2. Designing Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3. Technical Risks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4. Architecture Evolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5. Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 6. Quality Assurance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Collaborate or fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Technical leadership is a role, not a rank . . . . . . . . . . . . . . . . . . . . . . . 20 Create your own definition of the role . . . . . . . . . . . . . . . . . . . . . . . . 20 8. Should software architects code? . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Writing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Building prototypes, frameworks and foundations . . . . . . . . . . . . . . . . . 23 Performing code reviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Experimenting and keeping up to date . . . . . . . . . . . . . . . . . . . . . . . . 23 The tension between software architects and employers . . . . . . . . . . . . . . 24 You don’t have to give up coding . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Don’t code all the time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 9. Software architects should be master builders . . . . . . . . . . . . . . . . . . 26 State of the union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Back in time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

CONTENTS Did master builders actually build? . . . . . . . . . . . . . . . . . . . . . . . . . 27 Ivory towers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Divergence of the master builder role . . . . . . . . . . . . . . . . . . . . . . . . 29 Achieving the role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Architects need to work with the teams . . . . . . . . . . . . . . . . . . . . . . . 31 10. From developer to architect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Experience is a good gauge but you need to look deeper . . . . . . . . . . . . . . 32 The line is blurred . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Crossing the line is our responsibility . . . . . . . . . . . . . . . . . . . . . . . . 33 11. Broadening the T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Deep technology skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Breadth of knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Software architects are generalising specialists . . . . . . . . . . . . . . . . . . . 35 Software architecture is a technical career . . . . . . . . . . . . . . . . . . . . . . 36 12. Soft skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Stay positive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 13. Software development is not a relay sport . . . . . . . . . . . . . . . . . . . . 39 “Solution Architects” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Somebody needs to own the big picture . . . . . . . . . . . . . . . . . . . . . . . 40 14. Software architecture introduces control? . . . . . . . . . . . . . . . . . . . . . 41 Provide guidance, strive for consistency . . . . . . . . . . . . . . . . . . . . . . . 41 How much control do you need? . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Control varies with culture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 A lever, not a button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 15. Mind the gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Developers focus on the low-level detail . . . . . . . . . . . . . . . . . . . . . . . 43 Architects dictate from their ivory towers . . . . . . . . . . . . . . . . . . . . . . 43 Reducing the gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 A collaborative approach to software architecture . . . . . . . . . . . . . . . . . 45 16. Where are the software architects of tomorrow? . . . . . . . . . . . . . . . . . 46 Coaching, mentoring and apprenticeships . . . . . . . . . . . . . . . . . . . . . . 47 We’re losing our technical mentors . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Software teams need downtime . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

CONTENTS 17. Everybody is an architect, except when they’re not . . . . . . . . . . . . . . . 49 Everybody is an architect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Except when they’re not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Does agile need architecture? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 18. Software architecture as a consultant . . . . . . . . . . . . . . . . . . . . . . . 52 Domain knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 19. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 III Designing software . . . . . . . . . . . . . . . . . . . . . . . . . 55 20. Architectural drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 1. Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2. Quality Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 3. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4. Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Understand their influence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 21. Quality Attributes (non-functional requirements) . . . . . . . . . . . . . . . . 58 Which are important to you? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 22. Working with non-functional requirements . . . . . . . . . . . . . . . . . . . 62 Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Refine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 23. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Time and budget constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Technology constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 People constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Organisational constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Are all constraints bad? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Constraints can be prioritised . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Listen to the constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 24. Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Development principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

CONTENTS Architecture principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Beware of “best practices” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 25. Technology is not an implementation detail . . . . . . . . . . . . . . . . . . . 72 1. Do you have complex non-functional requirements? . . . . . . . . . . . . . . . 72 2. Do you have constraints? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 3 Do you want consistency? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Deferral vs decoupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Every decision has trade-offs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 26. More layers = more complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Time and budget - nothing is free . . . . . . . . . . . . . . . . . . . . . . . . . . 76 27. Collaborative design can help and hinder . . . . . . . . . . . . . . . . . . . . . 78 Experience influences software design . . . . . . . . . . . . . . . . . . . . . . . . 78 28. Software architecture is a platform for conversation . . . . . . . . . . . . . . 80 Software development isn’t just about delivering features . . . . . . . . . . . . . 80 29. SharePoint projects need software architecture too . . . . . . . . . . . . . . . 82 1. Many SharePoint implementations aren’t just SharePoint . . . . . . . . . . . . 82 2. Non-functional requirements still apply to SharePoint solutions . . . . . . . . . 82 3. SharePoint projects are complex and require technical leadership too . . . . . . 83 4. SharePoint solutions still need to be documented . . . . . . . . . . . . . . . . . 83 Strong leadership and discipline aren’t just for software development projects . . 83 30. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 IV Communicating design . . . . . . . . . . . . . . . . . . . . . . 85 31. We have a failure to communicate . . . . . . . . . . . . . . . . . . . . . . . . . 86 Abandoning UML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Agility requires good communication . . . . . . . . . . . . . . . . . . . . . . . . 88 32. The need for sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Test driven development vs diagrams . . . . . . . . . . . . . . . . . . . . . . . . 89 Why should people learn how to sketch? . . . . . . . . . . . . . . . . . . . . . . 89 Sketching isn’t art . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

CONTENTS Sketches are not comprehensive models . . . . . . . . . . . . . . . . . . . . . . . 90 Sketching can be a collaborative activity . . . . . . . . . . . . . . . . . . . . . . . 91 33. Ineffective sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 The shopping list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Boxes and no lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 The “functional view” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 The airline route map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Generically true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 The “logical view” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Deployment vs execution context . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Too many assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Homeless Old C# Object (HOCO) . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Choose your own adventure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Stormtroopers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Should have used a whiteboard! . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Creating effective sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 34. C4: context, containers, components and classes . . . . . . . . . . . . . . . . . 105 A common set of abstractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Summarising the static view of your software . . . . . . . . . . . . . . . . . . . . 107 Common abstractions over a common notation . . . . . . . . . . . . . . . . . . . 107 Diagrams should be simple and grounded in reality . . . . . . . . . . . . . . . . . 108 35. Context diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 36. Container diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 37. Component diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

CONTENTS Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 38. Shneiderman’s mantra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Overview first (context and container diagrams) . . . . . . . . . . . . . . . . . . 127 Zoom and filter (component diagrams) . . . . . . . . . . . . . . . . . . . . . . . 127 Details on demand (class diagrams) . . . . . . . . . . . . . . . . . . . . . . . . . 127 Understanding a large and/or complex software system . . . . . . . . . . . . . . 127 39. Technology choices included or omitted? . . . . . . . . . . . . . . . . . . . . . 128 Drawing diagrams during the design process . . . . . . . . . . . . . . . . . . . . 128 Drawing diagrams retrospectively . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Architecture diagrams should be “conceptual” . . . . . . . . . . . . . . . . . . . . 129 Make technology choices explicit . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 40. Would you code it that way? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Shared components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Layering strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Diagrams should reflect reality . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 41. Software architecture vs code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Abstraction allows us to reduce detail and manage complexity . . . . . . . . . . . 134 We talk about components but write classes . . . . . . . . . . . . . . . . . . . . . 135 An architecturally-evident coding style . . . . . . . . . . . . . . . . . . . . . . . 135 Package by layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Package by feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 The model-code gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Packaging by component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Layers are an implementation detail . . . . . . . . . . . . . . . . . . . . . . . . . 141 Aligning software architecture and code . . . . . . . . . . . . . . . . . . . . . . . 141 42. Software architecture as code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Auto-generating software architecture diagrams . . . . . . . . . . . . . . . . . . 143 Why isn’t the architecture in the code? . . . . . . . . . . . . . . . . . . . . . . . 145 Auto-generating the software architecture model . . . . . . . . . . . . . . . . . . 147 Creating a software architecture model as code . . . . . . . . . . . . . . . . . . . 148

CONTENTS Visualising the software architecture model . . . . . . . . . . . . . . . . . . . . . 151 Software architecture as code opens opportunities . . . . . . . . . . . . . . . . . 154 The road ahead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 43. You don’t need a UML tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 There are many types of UML tool . . . . . . . . . . . . . . . . . . . . . . . . . . 155 The simplest thing that could possibly work . . . . . . . . . . . . . . . . . . . . . 156 Uses for UML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 There is no silver bullet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 44. Effective sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Colour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Diagram review checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Listen for questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 45. C4++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Enterprise context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 User interface mockups and wireframes . . . . . . . . . . . . . . . . . . . . . . . 166 Domain model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Sequence and collaboration diagrams . . . . . . . . . . . . . . . . . . . . . . . . 167 Business process and workflow models . . . . . . . . . . . . . . . . . . . . . . . 167 Infrastructure model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Deployment model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 And more . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 46. C4 - FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 System names on context diagrams . . . . . . . . . . . . . . . . . . . . . . . . . 169 Should I use actors or boxes for external systems? . . . . . . . . . . . . . . . . . 169 Mixing levels of abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Shared components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

CONTENTS Utility components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 47. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 V Documenting software . . . . . . . . . . . . . . . . . . . . . . . 172 48. The code doesn’t tell the whole story . . . . . . . . . . . . . . . . . . . . . . . 173 The code doesn’t portray the intent of the design . . . . . . . . . . . . . . . . . . 174 Supplementary information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 49. Software documentation as a guidebook . . . . . . . . . . . . . . . . . . . . . 177 1. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 2. Sights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 3. History and culture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 4. Practical information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Keep it short, keep it simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Beware of the “views” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Product vs project documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 182 50. Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 51. Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 52. Quality Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

CONTENTS 53. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 54. Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 55. Software Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 56. External Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 57. Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 58. Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

CONTENTS Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 59. Infrastructure Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 60. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 61. Operation and Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 62. Decision Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 63. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 VI Agility and the essence of software architec- ture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 64. The conflict between agile and architecture - myth or reality? . . . . . . . . . 212 Conflict 1: Team structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

CONTENTS Conflict 2: Process and outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Software architecture provides boundaries for TDD, BDD, DDD, RDD and clean code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Separating architecture from ivory towers and big up front design . . . . . . . . . 214 65. Quantifying risk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Probability vs impact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Prioritising risk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 66. Risk-storming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Step 1. Draw some architecture diagrams . . . . . . . . . . . . . . . . . . . . . . 218 Step 2. Identify the risks individually . . . . . . . . . . . . . . . . . . . . . . . . . 218 Step 3. Converge the risks on the diagrams . . . . . . . . . . . . . . . . . . . . . 219 Step 4. Prioritise the risks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Mitigation strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 When to use risk-storming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Collective ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 67. Just enough up front design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 It comes back to methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 You need to do “just enough” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 How much is “just enough”? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Firm foundations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Contextualising just enough up front design . . . . . . . . . . . . . . . . . . . . . 228 68. Agility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Understanding “agility” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 A good architecture enables agility . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Agility as a quality attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Creating agile software systems in an agile way . . . . . . . . . . . . . . . . . . . 233 69. Introducing software architecture . . . . . . . . . . . . . . . . . . . . . . . . . 235 Software architecture needs to be accessible . . . . . . . . . . . . . . . . . . . . . 235 Some practical suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Making change happen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 The essence of software architecture . . . . . . . . . . . . . . . . . . . . . . . . . 239 70. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

CONTENTS VII Appendix A: Financial Risk System . . . . . . . . . . 242 71. Financial Risk System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Functional Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Non-functional Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 VIII Appendix B: SoftwareGuidebook for techtribes.je 247

Preface The IT industry is either taking giant leaps ahead or it’s in deep turmoil. On the one hand we’re pushing forward, reinventing the way that we build software and striving for craftsmanship at every turn. On the other though, we’re continually forgetting the good of the past and software teams are still screwing up on an alarmingly regular basis. Software architecture plays a pivotal role in the delivery of successful software yet it’s frustratingly neglected bymany teams.Whether performed by one person or shared amongst the team, the software architecture role exists on even the most agile of teams yet the balance of up front and evolutionary thinking often reflects aspiration rather than reality. Software architecture has a bad reputation I tend to get one of two responses if I introduce myself as a software architect. Either people think it’s really cool and want to know more or they give me a look that says “I want to talk to somebody that actually writes software, not a box drawing hand-waver”. The software architecture role has a bad reputation within the IT industry and it’s not hard to see where this has come from. The thought of “software architecture” conjures up visions of ivory tower architects doing big design up front and handing over huge UML (Unified Modeling Language) models or 200 page Microsoft Word documents to an unsuspecting development team as if they were the second leg of a relay race. And that’s assuming the architect actually gets involved in designing software of course. Many people seem to think that creating a Microsoft PowerPoint presentation with a slide containing a big box labelled “Enterprise Service Bus” is software design. Oh, and we mustn’t forget the obligatory narrative about “ROI” (return on investment) and “TCO” (total cost of ownership) that will undoubtedly accompany the presentation. Many organisations have an interesting take on software development as a whole too. For example, they’ve seen the potential cost savings that offshoring can bring and therefore see the coding part of the software development process as being something of a commodity. The result tends to be that local developers are pushed into the “higher value” software architecture jobs with an expectation that all coding will be undertaken by somebody else. In many cases this only exaggerates the disconnect between software architecture and software

Preface ii development, with people often being pushed into a role that they are not prepared for. These same organisations often tend to see software architecture as a rank rather than a role too. Agile aspirations “Agile” might be over ten years old, but it’s still the shiny new kid in town andmany software teams have aspirations of “becoming agile”. Agile undoubtedly has a number of benefits but it isn’t necessarily the silver bullet that everybody wants you to believe it is. As with everything in the IT industry, there’s a large degree of evangelism and hype surrounding it. Start a new software project today and it’s all about self-organising teams, automated acceptance testing, continuous delivery, retrospectives, Kanban boards, emergent design and a whole host of other buzzwords that you’ve probably heard of. This is fantastic but often teams tend to throw the baby out with the bath water in their haste to adopt all of these cool practices. “Non-functional requirements” not sounding cool isn’t a reason to neglect them. What’s all this old-fashioned software architecture stuff anyway? Many software teams seem to think that they don’t need software architects, throwing around terms like “self- organising team”, “YAGNI” (you aren’t going to need it), “evolutionary architecture” and “last responsible moment” instead. If they do need an architect, they’ll probably be on the lookout for an “agile architect”. I’m not entirely sure what this term actually means, but I assume that it has something to do with using post-it notes instead of UML or doing TDD (test-driven development) instead of drawing pictures. That is, assuming they get past the notion of only using a very high level system metaphor and don’t use “emergent design” as an excuse for foolishly hoping for the best. So you think you’re an architect? It also turns out there are a number of people in the industry claiming to be software architects whereas they’re actually doing something else entirely. I can forgive people misrepresenting themselves as an “Enterprise Architect” when they’re actually doing hands- on software architecture within a large enterprise. The terminology in our industry is often confusing after all. But what about those people that tend to exaggerate the truth about the role they play on software teams? Such irresponsible architects are usually tasked with being the technical leader yet fail to cover the basics. I’ve seen public facing websites go into a user acceptance testing environment with a number of basic security problems, a lack of basic performance

Preface iii testing, basic functionality problems, broken hyperlinks and a complete lack of documenta- tion. And that was just my external view of the software, who knows what the code looked like. If you’re undertaking the software architecture role and you’re delivering stuff like this, you’re doing it wrong. This isn’t software architecture, it’s also foolishly hoping for the best. The frustrated architect Admittedly not all software teams are like this but what I’ve presented here isn’t a “straw man” either. Unfortunately many organisations do actually work this way so the reputation that software architecture has shouldn’t come as any surprise. If we really do want to succeed as an industry, we need to get over our fascination with shiny new things and starting asking some questions. Does agile need architecture or does architecture actually need agile? Have we forgotten more about good software design than we’ve learnt in recent years? Is foolishly hoping for the best sufficient for the demanding software systems we’re building today? Does any of this matter if we’re not fostering the software architects of tomorrow? How do we move from frustration to serenity?