Visualise, document and explore your software architecture - Simon Brown

right good morning folks everybody good after the conference party last night good year is currently 2017 let's imagine the air is now twenty thirty seven and teleportation has finally been invented hooray and I teleport us all to here where are you there France ya lo Rue du something sounds French Jersey yeah so this is why I live if you wanted to really find out where you were you could walk down this road down this leafy Lane and hopefully bump into somebody and are somewhere am I or we could use technologies to solve this problem we get out our mobile devices our smart phones we open up on the maps apps we hit the little dot that satisfy me and it gives you something like that does this help does this help you understand where you are a bit we've got a nicer overhead view now it's still quite zoomed in isn't it still not entirely sure where we are how do we solve this we do the pinch to zoom out thing there we go there coz that's where I live this is a small island just off the coast of France it's quite complex isn't it it's quite cluttered that picture you can see lots of the textures the different shades of green it's not a particularly great way to navigate to an unfamiliar environment again how do we solve this problem with technology we just removed the satellite imagery there we go now Jersey becomes a bit clearer we can see the intricate network of roads and lanes and please to start sison the place names if you don't know where Jersey is so again this is kind of useless so we have to do the pinch to zoom out a bit more context as another islands next door called Guernsey this here on the on the right is France we zoom out one more time I there we go now we can start to get some some better context about where Jersey is zoom out one more time whose vintage Jersey here a couple of people right so this summer coming when it will when the weather warms up because no we are so British climate essentially you should come to Joseon holiday when you come through the airports also to one of the harbours grab one of these things it's a visitor map the Vista map is a really good simple guide to getting around Jersey tells you where to go what the place names are that sort of thing it's broke up into four quarters nice simple map it's mostly accurate it's a kind of schematic thing there's a bit of information and detail missing but this does tell you the major route ways sites points are interest there's a town area we can zoom in a bit again this is mostly accurate you'll see that there's a a marina here which is blue it kind of implies it's covered by water it is for 12 hours of the day if you drive your boat in there and park it you will come back at some point and find it's laying on its side so that completely dries out and also there's a bathing pool at the bottom just where it says sand Helier that gets flushed twice a day with the earth that the tiler movement we have which is probably useful because I mentioned the kids peeing it and some of it whatever so contrast this map which is very simple to this one this is an ordnance survey map of Jersey and it's much more detailed it's but it's been created by you know modeling and surveying and it's got every single streets and every single curve and every single building and every single building shape and the various terrains and the contour lines and it's it's very very detailed this is a little bit trickier to understand but it's got lots of information if you know how to interpret it the thing both these maps have in common is they show points of interest so when you come to Jersey what should I go and see well one of the things you should go and see is this it's called a list with Castle it's a small islets off the south coast of the island because of the history around Jersey the French and the British Connor invading there was lots of fortifications and this castle was built in the fifteen or 1600s and it's a really beautiful example of like a kind of medieval style castle lots of big granite stone work that sort of thing when you walk to the center of this castle there is a kind of natural high point and you get closer and you get closer and you get closer and then you see something a bit odd you've got this beautiful granite building and someone stuck this really ugly concrete thing on top you like what why would you do that you walk around the castle a bit more our history is important here so during World War two this is my short history lesson during World War two Jersey was occupied by the German forces the Germans imported a bunch of concrete and built stuff like that they also built gun emplacement so they refortified the existing fortifications and again it's only by reading the signs around the castle that you really understand this history and it allows you to kind of marry these two different styles of architecture together in your mind how do you find out more information about the history where do you buy a travel guide book before you come to Jersey which you should the summer of course physical book electronic book tells you lots of really interesting information about Jersey maps points of interests walking routes sites itineraries and so on and so forth so what does this got to do with anything I'm not being paid here by the Jersey tourism bullet by the way to promote Jersey although they should do I'll come back to that stuff later so visualize this talk is really about visualizing documenting and exploring software architecture one of the things I do at the moment is travel around the world and I help organizations understand software architecture I run a one or two day workshop and a big part of that workshop is a it's a software architecture kata so here are some requirements go away creative solution draw some pictures to visualize it the diagrams that are flying pass now are real examples from real workshops there's some really really crazy stuff going on from these diagrams I have 20 gigabytes of photos like this but we could just spend the next three or four days as looking all these diagrams sometimes when I'm listening in to what the groups are doing so this is a group exercise three or four people sometimes somebody in the group will be drawing a thing like a shape or a line or a symbol and they will actually say things like this right this thing doesn't make sense that we're drawing but we'll explain later whoops and there's always this assumption that diagrams will be presented and there's always this assumption that you know there's a narrative needed to accompany the diagrams to really unlock the meaning of the diagrams and of course this is fine if you're working in a nice or group environment and you're having like an hour and a half or two hours to design a software solution you're doing some pictures you're having those conversations in front of whiteboard those conversations those diagrams those icons make sense to you one of the really nasty tricks I play is I get groups to swap pictures and guess what happens you get this gigantic what moment going on because they've now got a bunch of diagrams they don't know what they mean they've got funny symbols funny icons it's just really really hard to interpret so I ask people well what's tricky about these diagrams you have you know give me some review here and they say well we're not sure what these shapes of arrows mean you know why these lines pink or reds or what somebody had a pink marker pen they used it you know what is this diagram actually showing what level of detail is it showing why have we got multiple diagrams which order do you read the diagrams in and so on and so on and so on the actual design parts that exercise is really simple it's a really really simple little kind of batch application with a web app typically but the complexity in this exercise is just communicating and visualizing and sharing these ideas you know the intent behind the design so our seems what did you find challenging and they all say the same thing we don't know where to start with the drawings we don't know what types of diagrams we should be creating here what notation should we really be using what level of detail do we design down to and what level of detail do we draw pictures down to these are two very different things of course I run this workshop now a lot twenty-five plus countries ten thousand plus people have done it I have no empirical evidence to back anything up right this is all purely anecdotal based on this sort of sample size but essentially software architects and software developers really struggle with this stuff time and time and time again everybody struggles with this exercise it seems now we might be thinking well there is this thing called the unified modeling language who uses UML here one I did ask that question out loud didn't I one okay so all that words well then there and that's again what I'm seeing more and more so um oh used to be quite widely used maybe ten twelve fifteen years ago now hardly anybody's using it I'm seeing many many more organizations and teams where nobody on on the team understands UML and typically and actually I think this is optimistic it's sort of one out of ten people I mean given this audience this is way way up to Mystics course so this raises a rather interesting question is UML worth using for describing software specifically architecture and design ideas and the answer is it can be the problem with UML is it doesn't necessarily have the right type of abstractions that are useful to describe software systems so let's imagine we want to draw a picture of a user using a software system you can't do that in UML UML does not have a software system box what you end up doing typically is using something like a component or a package shape and adding a little stereotype of brackets to say this is not a component as you might think it's a component it's actually a software system if you're having to jump through these sorts of hoops you have to question whether UML's the right notation to use in the first place and this is why lots of people draw boxes and lines types diagrams if you've never drawn after it's a diagram before where do you go for inspiration well Google's a good start except it's not if you go and do a Google search for soft architecture diagram you get that page after page after page of very pretty colorful block pictures the type of things you can do in PowerPoint Visio OmniGraffle keynote lucid chart except to accept etc and when I go and see organizations and they let me look at the documentation I see stuff like this typically on the you know SharePoint or confluence pages and lots of these diagrams don't make sense lots of these diagrams suffer from exactly the same problems as the hand-drawn diagrams are kind of wizard quickly before why it's not this important goods communication rule seeking to be you know leaner and more agile and move fast to respond to business changes and business needs if you want to do that as a team you need good communication that's all this is very simply about there are two things we want to talk about then really number one is notation and number two is content notation is super simple to solve here are some tips I'm going to go through these in any detail but you know these are the types of things you want to think about if you're drawing ad hoc boxes and lines diagrams to describe your software systems be conscious of the notation you're using every time you invent an icon or a symbol or a specific line type ask yourself why and make sure that's written down with a key or a legend one of the things we joke about and software is that naming stuff is really hard do you think this is true yeah it's to two degree isn't it if naming stuff is hard it doesn't make any sense whatsoever that most of our architected diagrams are just boxes with one word in one name if the name of the thing is wrong there's just a degree of ambiguity creeps in these diagrams so my simple my really simple advice here is just add more texts to your pictures it's as simple as that there's an example diagram the one on the left is what I see people normally do lots of boxes single word add more text describe what those boxes are what technologies are these boxes one of the responsibilities of these boxes and again I'll show you some more examples this later so it notations easy contents much more interesting back in the late 90s Philip Christine who's one of the Rough Guides Maskelyne for a process he created this thing here called the the four plus one view model of software architecture and it's a way to think about describe and communicate software architecture from a number of different angles essentially and he says this to describe a software architecture we use a model composed of multiple views or perspectives anybody using this today anybody use it in the past a couple of people so essentially what this is all about is you take a use case a scenario a feature a user story and you document it from four different angles you have a logical view that talks about your functional building blocks we can call them modules or components if we want to you have a development view which Maps how your functional logical building blocks map on to code there's a process view that talks about concurrency and there's a physical view talks about infrastructure and deployment there are lots of other ways to do this as well there are lots of other architecture books and those architecture books processes present their own enhancements or extensions or versions of this and the thing you'll notice about most of them is that they have this weird split between the logical view and the development view so here's a picture of my software system it's made up of logical things and here's a very different picture of what those logical things look like if they're hopefully mapped code somehow and this is weird I don't know why we've chosen to do this in the past you can see this in some of the older design methodologies like SS ADM there's a logical design step and then there's a physical design step and this doesn't make any sense as far as I'm concerned because the two intertwined of course and I think this leads to this statements a lot and I see this in organizations around the world they have these beautiful looking handcrafted architecture diagrams printed on like a zero paper with a plotter last updated 1998 something and then they say yeah these items are really nice but they don't quite match the code by the way right so they're lying to you what value to these diagrams have you is there just a big crack that you're covering up or do you actively use these diagrams on a daily basis so again it's a mismatch between what we think about on the diagrams and what the code looks like it's fantastic book if you're really interested in software architecture there's a fantastic book by George Fairbanks it's called just enough software architecture in this book George Fairbanks talks about the model codes GAAP and it's exactly this thing so we have a model of our software a bunch of diagrams if you will and that model of our software doesn't quite reflect the code or vice versa and explaining this is very very simple so when we're having an architecture discussion we might use abstract concepts to describe the things in our system we might have a discussion using the terms component and module and layer and service and subsystem who's a c-sharp net developer here right so that's a good chunk you in c-sharp is there a component keyword Oh in c-sharp is there a layer keyword oh but we often think about our software as being made up of layers and components and we have these conventions where we say things like well a namespace equals a component or a namespace equals a layer or maybe an assembly equals a component and sometimes it's that mapping of you know real-world code concepts into the abstract concepts that doesn't make sense and is often missing so that's the sort of prom winners whole fear before we can even attempt to solve this problem this gap we have a much much more pressing issue and that is even now in 2017 we don't have a common language to describe architecture we don't have a common language to describe the things our systems are built from now this is a pretty bold thing to say I must admit because we've been using words like modular component and services layer for years and years and years so surely we must understand this who likes a quick quiz do a quick quiz excellent right what's that it's a map of London perfect we're in the right place what's this blue thing in the middle it's the terms it's a river what is a river wet yes to flowing body of water one way or the other perfect so we learnt this stuff when we were kids we know what a river is and we know how to go and find other rivers so I something else what's that it's a yeah it's a top-down floorplan for bathroom what's this thing here it's a toilet excellent what is a toilet seriously there's an exercise here for later right so it's another body of flowing water ideally one way again we learn this as a kid we know how to identify depending on country other toilets and we can go and identify more toilets if want to perfect any electrical people here excellent so what's the sort of squiggly thing down here there's a zigzaggy thing a resistor what is a resistor resist something or other yeah slows down the flow currents are not less compression if I had a box of electrical components here on this table with resistors and capacitors and switches and LEDs and all sorts of stuff could you come to the front rummage through the box and find me resistor yeah and if you knew the colour coding you could work out how strong that resistor so again we know the resistor is we can identify it we can pick it up touch your feet up see this crease is far too simple right let's go exponential what's that see it was sat for that what okay let's let's let's backtrack what type of diagrams are these class diagrams closed for not quite component right so these are UML component diagrams in in various different formats given that these are UML component diagrams what are each of the boxes on the diagrams components thank you yeah so each of these boxes is a component that's what this UMail shape or notation means what's the component uh-huh something that does something I ran my workshop late last year and somebody says it's an imaginary thing right so you've built six software systems out of imaginary things it's a lot it's a logical unit function yeah that kind of works as a as an explanation let's look a bit closer these diagrams so that one there is stereotyped database so that is a database component because there's a little stick for the lollipop saying JDBC that sounds like there is a Java interface into that database so that sounds like a database right like my sequel instance or something so that's component on the left-hand side we've got some components that are labeled UI or application I don't know whether these are web applications console applications mobile applications I don't know if these are separately deployed or things the slice through the middle you remember what I said about naming and adding more text I have no idea what these components are what they do seminar schedule brilliant I don't know whether these components are micro services right they're standalone deploy of all things with a remote interface or they could be part of the application there's just so much ambiguity on this diagram the other one is absolutely brilliant so this is a real example from modeling tool I went to live which one there's a firewall component I guess there's an XSL stylesheets component what what else have we got there's a web server component and ASP pages component I don't think it ever drawed an architect's diagram like that my favorites of course is the business logic component that's epic to boil this down to its absolute essence right imagine we're building a software system the software system is is built from a web application that talks to a database if you go and lock up the word component in the dictionary it means part of something bigger for some people in the room the web application is a part of the system it's a component of the system for other people in the room that login component is a component both makes sense but they're just very different levels of abstraction it's the irony of the ubiquitous language we talk about domain driven design and creating this ubiquitous language between us as techies and the business people we don't have our own ubiquitous language that's exactly what this is about if you look at the environment language UML it tried to do two things it tried to create a ubiquitous language and a ubiquitous notation to describe the language I think having the common set of abstractions I think creating the vocabulary is actually much much more important than the standardized boxes and lines if you look at something like electrical engineering if I draw a little squiggly thing we know it's a resistor I really would like us as an industry to get to that point but I don't think we're there yet and I think we need to focus on the abstractions first and let the notations evolve naturally this might sound a bit foolish go get to tourist maps of London and lay them out side by side the two toys maps of lund will show the same things won't they the various areas and districts and the Thames and the tube lines and the bus routes and the shopping centers and out sorting so the two maps of London will show the same things the same abstractions but they might use a different notation different shadings colors line styles icon cymbals how do we decipher the maps whether the key in the corner perfect let's do that it's so a map is a really nice simple example of a common set of abstractions with the self-describing notation and that's a really really powerful concept so how do I think about software systems for me a software system is made up of a number of containers a container is something like an application or a data store it's a web app a mobile app a console app a Windows service a database a file system and Amazon s3 bucket something when you in resolver ever it's something that needs to be running for your system to work for me my containers are made up of components so I want to use word components means something running in a runtime environment essentially yeah it's a grouping of related stuff with a nice clean simple interface and because I mostly deal with Java and c-sharp my components are built from classes ultimately and we're done so this is a really really simple hierarchical structure to describe the static structure of a software system software systems containers components classes if you're using f-sharp not really classes are there so maybe an f-sharp it's not components and classes maybe it's modules and functions casts cow same thing JavaScript modules and functions modules and objects so you might have to take this hierarchical approach and kind of map it to the tech that you're using this is my language this is my set of abstractions we can then draw some pictures to visualize this stuff and this is what I call the c4 model our system context diagram shows my system and stuff around it we zoom into the system boundary to show containers we zoom into each container to show components and then we probably stop what I normally find is going down to the level of components is normally sufficient to describe my software if you want more detail and specific components yet you can zoom in if you want to if anyone's started to work around big data you might have heard of Schneiderman spectra if you have a huge amount of stuff to work with you want an overview of something first you don't want to zoom in and filters just specific parts of that set and then you want some details on demand and it's the same sort of thing this is a really quick SIL example when I moved back to Jersey 2008 I built this thing here Tek time CA it's a really super simple content aggregator for the local tech industry I've now since taken it down list local people businesses blog posts tweets out something this is a system context diagram for the tech drive system that box in the middle that's my system and these are the things around it different people users actors roles personas and different system dependencies if this is interactive like a Google map we select the tech toys box we pinch to zoom in we get to see the content inside it so this dashed line here represents the system boundary and all of the boxes inside the system boundary are the containers that make up the tech drive system there's a web app a standalone app and some data tools you'll notice my diagrams I have lines descriptions technologies the arrows are annotated so on and so forth again if we're interested in some more detail we select one of the containers we pinch the zoom in we get to see components so this is the component diagram for one of those containers and the story repeats until we get down to a class diagram so nice simple set of hierarchical diagrams that actually reflect the structure and thing we're building and it's all about maps it's the same thing as I presented at the start we have different levels of maps for different audiences depending on the different types of stories that we want to tell and we do want a way to zoom in from one level to the next and there to be some real traceability here of course this is just about static structure I am trying to you know tackle this static structure first so we have the codes up to the system with a couple levels in between once you understand that static structure the other views that you might want to use to describe your software are super simple if you have a feature or user story or use case that you want to show how it works at runtime you draw a UML sequence or collaboration diagram showing how elements in the static model interactive run phone whether they are classes components or containers up to you if you have a map of your infrastructure Reuters firewall service that sort of thing whether it's virtualizer physical there's a mapping between containers and infrastructure that's your deployment mapping again super simple to do so so I teach on my course people tend to love it suddenly this week asked me if I was going to submit it to a standards body which sort of scared me I'm not sure how I answer the question and I force people to do this on paper and it really bugs them because there's me saying add more text to your diagrams and now they're going nuts or angle this little tiny text I'm pissed on pieces of paper so after this at some point I always get this question well what tooling do we recommend and whenever I polled a team I said well what tooling to use currently and they say how we use video OmniGraffle or Gliffy or draw the i/o because we use in the cloud now or lucidchart or Die Agri diagram Lee there are lots and lots of these kind of general-purpose diagramming tools out there and I'm sure you've used them in the past as well and because the diagrams I'm showing you just boxes and lines you can draw them in general-purpose tooling you create a box you put some text in it you make the text the right size the right color you line it up we draw another box with the same thing you draw a line between the two boxes you open up the properties for the line you try and figure out which is the start and end of the line to put the right Arrowhead on the right side you always get it wrong first time around trust me and you kind of rinse repeat and it's a very manual laborious process the other thing of course with something like Visio or a static diagramming tool is that if you have the same box on two diagrams if you change it on one diagram it doesn't magically change on the second one so if I rename a person a user component I have to go and rename that thing on other diagrams with great power comes great responsibilities come on its 2017 the building people do this you know you've been tasked with architecting the Burj Khalifa do you get video out I hope not but the building industry uses you know sophisticated complex modeling tools okay a nice three-dimensional model of the thing we're building and we surface different diagrams different use from it cross-sections and side elevations and so on the irony of this of course the irony of this is that we build these tools for other people to do modeling but we can't do modeling ourselves have fun is that once you have codes why don't we just reverse engineer diagrams from code has anybody tried this what happens you get an awful mess is that because your code is an awful mess sometimes but more often than not these diagramming tools are just showing you everything at a very very low level of DS of course apologies for that the Java nature of this example but everything I'm going to tell you is exactly applicable teashop so in the in the Java world there's a framework called spring spring does everything that's we need to know part of spring is an MVC framework for building a model view controller web apps like air speed on MVC this diagram on the left is is an architect's diagram for a sample application called the spring pet clinic so this is a Twix a ssin a toy code base to illustrate how to build spring MVC applications basically it's a three layer architecture controllers services repositories you download the code of github it looks like this you load it into your IDE you say IDE generate me a class diagram of all of this lovely kony get that this is a small sample toy application we like 20 or 30 things this is not your enterprise systems with millions and loads of code I did I promise you I did try to move these boxes around so there were no overlapping lines is basically impossible it's too much detail if we take a more thoughtful balanced view maybe we exclude some stuff that's not really important so having an architected discussion and again this varies code base to code base but in this example if I start to remove some of the really boring things like your mighty utility classes and my data structures that don't have any business logic in I can generate a much much simpler diagram by removing stuff in there from that diagram and once you start to rearrange the boxes I can now redraw that layer diagram again so the boxes at the top the classes are softened my web app controllers there's a bunch of service stuff in them all that's my business logic layer my service layer and all of the things down here are my repositories my decorator subjects but this is still fundamentally showing code isn't it it's still showing me classes interfaces links between these things if this was a Google map this might be like Street View so let's imagine I live in Jersey I never been to London I fly to London for the first time I'm an estate on a train to London somehow I walk out of London Victoria Station and I'm lost uh-huh but I have my smartphone with me so I open up my smartphone and I do the find me now thing and then I switch to Street View so I'm standing outside the train station I have the street view in real life and Google Street View here well that's a dumb idea isn't it it's like the same thing I'm just wasting my roaming data what I really want to do is zoom out of Street View to get a more you know high level overhead view and that's the thing how do i zoom out from this picture well I have to make some assumptions if if this is showing me codes and classes and I want to see components I have to work out what a component means for me in this code base and this is my approach for this code base so I'm going to treat all of the webapp controllers a set of components because they're separate things and I'm going to bundle up the interface and the implementation class for everything else down the bottom there's also some little tangle of helper classes so we may or may not want to include those in our component in our component definition so of course the diagramming tools when you reverse engineer the diagrams and code they see codes they don't see components and this is not a new problem of course this is just the model code a thing again we go back in time there's a great paper if you want to read it the first two opening paragraphs basically illustrate the whole thing you ask a developer to draw your diagrams and system their work you're going to get a nice high level picture you reverse engineer something from the code you get a totally different picture the low-level picture auto-generated is super accurate super precise but it doesn't necessarily match the way that me as a you know how I think of the co-pays and one the big promise here is that the the architectural information doesn't live in the code it gets lost at some point George Fairbanks to the rescue right so in George Fairbanks this book he talks about adopting an architecture 11 encoding star this sounds very grand is nothing more than dropping hints and metadata into your code base so that your code base does reflect your architectural ideas and intent in very real terms this is stuff like adopting a naming convention consciously so if I have a diagram here and there is a box that says logging component let's make sure something in the code is names logging components so there's nice one-to-one mapping maybe it's a name spacing or packaging convention maybe we say that every box on this component diagram maps to an assembly or a namespace maybe it's about adding machine readable metadata like attributes or annotations to say this is architectural e important this is our component for example I also want to get people away from the using video not because video is horrible but what it is but it's not the right tool to draw assets pictures now there's something called an architecture description language has Emily use one of these things before I thought that might be the case these things are essentially textual descriptions of architecture normally static structure so you write some text and that text describes your software system to some degree there are a bunch of these things out there darwin koala there's one called acme believe it or not and they never really left research in academia if you do a search for darwin architected description language online you end up on a university website there's a PDF file you can download with the language grammar it's horrible you did not want to go to conference all the teachers do these languages no no no however as developers we like texts that we we can diff text we have lots of tooling to support and read factor text we can check text in text is good for a number of reasons so why don't we take all of these ideas and throw them into a big pot and see what comes out so what I've done is I've created an execution an executable architected description language and there are two open source projects on github structure icing for Java and structure Iser for dotnet and essentially what these things are is they are small class libraries that implement the c-4 model we're going to show you some Java code the c-sharp version is almost exactly the same except you have to uppercase the first letter of the method names that's it what we're doing is we're really creating model of our system so let's create a model too that describes the spring pet clinic system the spring pet clinic system is nothing more than me as an employee of the clinic using the system that's it there's no more complexity here so basically I can create that description using code so I'm going to create myself a software system object and give it some properties to represent the the spring Peck clinic system and I'm going to create myself a person objects to represent the user and I'm going to say that using the API that the employee uses the system done that's it so it's a really nice simple kind to the main specific language to describe architecture you're just building up an in-memory object graph from a container perspective this is nothing more than our web app talking to our database again we can model out the code create container object for the web app create container object for the database why the two things together in various ways when it gets down to the level of components I don't want to have to do that why because it's long-winded and it's error-prone yeah we try we add a new feature you might change the list of components in your system so built into both libraries there's a component finder guess what the component finder does it finds components the naming is not hard after all you plug in different strategies because every codebase is different every codebase has a different approach to how it thinks about components so that part you can plug in your own strategies naming conventions so go and find me all of the things that end in the words components or service or controller for example in this case there's a pre-built spring component finder strategy it knows how spring applications work all it essentially does it looks for special Java annotations and then using some bundling logic it basically joins together the interface and the implementation class and it also finds some supporting helper classes so you run the components can you run this against the compiled version of the code so you run it against your assembly in the.net version it uses static analysis and reflection to go find stuff once you have a set of components and the relationships between them it finds those as well you can write some more code say things like go and find me all of the data access objects or data access components you just found and make them use a database so again you got complete control over all this stuff so that creates you a static model of your software with n crates and views there are a bunch of view classes in the library the view classes map onto the c4 diagrams we create a context view a container view component view and you get control over what you can add or remove from those from the pictures and then we need some pictures alright so this is just a little styling program we need some pictures we need to visualize this and of course what we have here is a model and once we have a model we can visualize it in a million different ways anybody like graph this here nope so in the Java library there's a graph is exporter so you take one of the views you export it to the graph biz format you throw it into graphics and you get an automatically generated diagram in the UML fans here one I know there's a so if you've heard of plants UML plant UML is at a textual way to create UML diagrams again there's an exporter for plant UML and it generates you a bunch of picture so these are UML diagrams to describe the spring pet clinic system context diagram container diagram components so all of these components were found by the components can plus all the links between them I want pretty diagrams for presentations and you know pretty diagrams that are just nicer so I bought some Tony constructor Iser structure Iser is a software service thing I have to do it carefully I'm not trying to sell raisa there is a commercial aspect of this if you want to do lots of kind of company sharing stuff but there's also a free version that you can create diagrams with with the free version what you do is you upload your model as a JSON documents to the Web API and it draws some pictures for you so there's no automatic layout but this is the context diagram for the spring pet clinic system it's the user using the system this is the container diagram it's the user using the web app the web acquiescing database and that's the component diagram so again a slightly nicer approach to visualization here again because this is a model we can generate things like diagram keys automatically array so now we can you know focus less on notation and again it's the diagrams the maps link what you can actually do with structure eyes the diagrams is you can double click on a box and there goes to the next level of detail down if anyone's seen the control contoso University sample asp.net sample again same sort of things so there's an example user system user web app database and these are the components in the contoso University sample those are the structure Iser diagrams somebody sent me an email a couple of weeks ago saying that they'd use the open source structure eyes of a c-sharp library and done an export to DG ml d g ml is natively supported by visual studio and you get some diagrams that look like this he's working to make diagrams look nicer but you get complete you know hierarchical expandable diagrams inside visual studio which is quite cool I don't know whether he's going to make this opens also commercial but you know definitely keep an eye out that so if you hook all of this stuff up with your build process guess what happens you get diagrams that reflect the code and diagrams that are kept up to date and that's exactly the point here we shouldn't have to worry about recreating diagrams every time we make some major changes to software such visualization in a nutshell there are two other parts this talk will just come the very very shortly documentation this is what the agile manifesto says about documentation these five words have been misinterpreted massively over the past 15 years and lots of teams don't write any documents anymore I'm sure you don't do that do you don't coming the problem is of course the codes doesn't tell you everything the codes can't tell you why decisions were made they can't tell you you know what the approach is to security on a holistic point of view where do we deploy this thing how do we maintain it and support it whether errors go that's hard to find just by scraping information from the code a lot of people are not teams still take this approach they create some sort of like software architecture documents there are millions of templates out there and they describe some really useful information very very badly you know typically these diagrams these are these documents are hundreds and hundreds of pages and a half the stuff is totally out of date that's why these are called SADS that's exactly how it makes you feel when you have to write these things how do I approach documentation naming I like the content in the software architecture documents I don't particularly like the implementation approach in many cases so what I do is I rename this to be a guidebook a software guidebook and it's the same thing we saw at the size of this talk so when it comes to Jersey you get a guidebook it gives you a nice simple overview some nice maps to navigate the unfamiliar environment that's what the diagram is to do of course the sites the points of interest the itineraries so you know given this island what's important what should I really go and see apply that to software systems given my million lines of code which I'd really talk about how do we support it deploy it maintain it so some of the practical information and also history and culture I given this software system this code bases for living for 10 or 20 years why has it evolved in the way it has let's write some of this stuff down and essentially in my documentation on describing what I can't get from the code that's it that's my simplest possible tip I can give you about documentation here this is a constantly evolving thing this is not big design up front where we creates 100 basic get it baseline and signed off and there are no more changes to it this is something we write in you know in complement to the code and the scope of this guidebook is a single software system the single product a single thing again people say what tooling do we use I don't care well if you want to use words go for it your new SharePoint good luck if you want to use confluence a lot of teams I work with they use confluence some of the teams now are using things like markdown and asciidoc that's crazy you know one file per section of the guidebook and then they have an automated build process takes the acid takes the markdown does some stuff with it generates HTML uploads it to a website subscription so again there are lots of options for creating documentation here how long should documentation be right forget about numbers of pages it's the wrong measure imagine I join your team I have no idea what your software does what I want is something I can read with a cup of coffee I have a couple of hours to give me a good starting point for exploring the code you fly over to Jersey on the 35 minute flight you read the guidebook on the way you get to Jersey you don't know exactly where everything is but you know what you want to go and see next so again it's that starting point for exploration and finally exploring now sometimes it's really useful to explore your code base to explore your software architecture model and that's the thing once you have a model of your code different levels of abstraction you can destroy it in really different ways this is a Java Script d3 visualization of the static structure for the spring pet clinic system so this is a visualization again provided for free structure Iser but Java Script d3 is very very simple and so you can create your own visualization very very simply so we have the spring pet clinic software system the containers the components the classes the code so for different levels of abstraction here we zoom in a bit this is this is showing you all of the code level elements for this particular component the different styling i've applied allows you to see different things about these classes or interfaces so this owner repository thing involved that's the interface type I've identified for the components during the component scan the not bowls with regular fonts the two of them there these are code elements classes in this case that are only part of this component and the gray code level elements are actually shared between this and other components so again you can apply some additional levels of exploration on top of a really simple model if you have a map of your components and their dependencies you can draw things like the Ben C maps so these are all of the components and the spring pet clinic web app what I've done is I've selected the clinic service and the different color lines are showing me ingoing and outgoing dependencies if there was some site click the pen sees we could highlight those things in red if you have some notion of size or complexity again you can do something like a bubble graph so this is showing you all of the components from the spring pet clinic web app ranked upon size where size is basically numbers of lines of code that make up that component you double click to zoom in you can see all of the code level elements again how big they are if you want to do more around exploring code bases something I would recommend is going to have a look at a product called code scene if anyone's familiar with atom torn Hill and his code as a crime scene book he's imited to his company they've built some tooling to explore a code base in addition to lots of similar kind of static analysis it actually does some human analysis on top so it's a you point at your source code system and it starts to show you know how do these people map onto this code base and it starts you can ask questions like you know are we following columns or commas or breaking ends on and so forth so it's a really interesting stuff in there right quick summary so the 2009 so there was a there's an article on infocomm from 2009 and it was a virtual discussion panel on the future of software architects documentation there are some big names here Grady Booch LEM bass or in woods and I've highlighted some really into doing things here yeah we want to see the architecture in the code we want to embed information we want to get information free with a click of a button I don't think we're there yet but hopefully some of the techniques and ideas and a tooling I showed you helps us get bit more towards that vision I have two things to fight to finish off with number one the 1990s is calling and it once is to land back please please please be please stop using video all Gliffy or lucid charts or draw day or any of those general-purpose diagramming tools for describing software and more importantly whatever tool you use whether it's whiteboards or pieces of paper within your team boundaries focus on the abstractions first so make sure you know how you're going to describe your systems and then let the notation evolve that's the simplest advice I could give you there so make sure you do have that you big's language in your team boundaries if you're more information on any of this stuff i've spoken about you can grab my books off lean pub you can actually read these for free online and all of the stuff we've talked about is in this book here number two that's me done thank you very much any questions yes oh I think the question says question is how much design and architecture and diagram should you do it front before you start writing code for me the short answer is I'm trying to do just enough right and that sounds a bit kind of blase but for me just enough is it's basically doing enough thinking to understand the structure of what you're building so in real concrete terms for me this means designing down to level of components and stopping so once you design down to levels of components which you can do very very quickly you get a really good view of how your responsibilities are carved up across a system so down to component level design unless you do micro versus you stop one level up you need to draw some diagrams like the diagrams I showed you so that's a really great way to share that vision and those are tech side is with other people on your team and it's also about risks so you look at your design say right where are our major risks you do a kind of risk identification exercise and then you might spike out some of those risky parts so that's my typical approach to doing upfront design and you know drawing the diagram is doing the design even for big systems you can do in a few days or a week you add a bit of prototyping proof of concept so you know for me I'd have an upfront design phase of a small number of weeks excellent question yes so it's the questions what's stopping this one game or attraction it actually is gaining more structure more traction so you should see my calendar is nuts the the universities are starting to realize that UML is not being used in industry some of the the better universities I've done some work with their University lectures are actually part-time software developers and part-time lecturers and what I see in those kind of more practical approaches to to university courses is that then they're now teaching things like my C formal in universities because they realize when these people get out into industry the whole UML thing is just wasted so we're getting there slowly there are other architectural formats sysml our cue mates begin the usage of those is very thin on the ground any questions over here yes structure Iser so I mean that's how I do this yeah so that the purpose of creating any tooling is to go back to creating real models of a software system so the probably got with static diagrams is that you make a change here you have to make that change in a bunch of other places if you go back to tools like rattle rose rational Software Architect sparks Enterprise Architect although those tools are big and complex and they tend to favor argument in you mailers notations the concept is still the same they're trying to give you a way to create a model of your software system you dragged the model elements on to diagram canvases you rename the thing in the model and the diagrams magically update so you know tooling aside what I would urge people to do is is to think about creating a model of their software system and ideally trying to get that model created as automatically from the code base as possible anything else over there yeah so - two crates and diagrams yeah so the question is if you have an existing code base how do you go about tracing some diagrams from it and what I would tend to do is I would tend to try and look at the code base and see right how can I identify components from this code base oh yeah start the bottom start the classes start understanding how you think about the code base you know what do you consider to be a component are using a layered architecture ports and adapters architecture you know how do you carve out component boundaries around sets of classes in some code bases that's really easy to do because it's been designed and built in a nice well-structured way if you have a more of a horrible legacy messy code base that's a bit tricky to do and sometimes you just have to say sorry we can't diagram this system because it's just really a mess and sometimes that gives you the empty the incentive you need to go inside things refactoring so on on existing code bases are definitely grinding it can be tricky excellent thank very much again

Channel: NDC Conferences

Views: 26,981

Rating: 4.9092784 out of 5

Keywords: architecture, simon brown, ndc, ndc london

Id: Ym9nhVZs89o

Length: 57min 25sec (3445 seconds)

Published: Tue Apr 18 2017

Reddit Comments

[u/MuletTheGreat]

Excellent talk. I just bought his two books and dumped them on my e-reader. Looks good!

[u/umlcat]

Cool.

And some companies put their UML / Software Architecture guy to maintain legacy apps. ...