Close more deals in IT architecture documentation

How to create outlook signature

this is phil copeman with a tutorial on software architecture and high level design this time we'll be talking about creating software architectures resulting in a high level design which is halfway down the left side of the v the elements of a high-level design document typically include an architecture as well as a more detailed high-level design itself the architecture is boxes arrows and sometimes interface descriptions the arrows or interfaces show communication paths between components with the components being the boxes architecture tends to be recursive one designer system is another designer's component that gets used in an even bigger system the high-level design document output by this process includes an architecture which provides nouns in the context of the requirements which provides the verbs once you have nouns plus verbs you understand what objects are supposed to perform what actions a concrete way to represent this is using sequence diagrams sds to show the interactions between components in the system anti-patterns for high-level design include skipping from requirements to code looking at a pile of requirements and just writing code almost always misses something and the hld is the piece that goes between them to bridge the gap another anti-pattern is not having a picture that shows how all the components fit together the third anti-pattern is relying solely on a wedding cake layer diagram like the one shown that does tell you which components are there it gives you some idea of which are on top of others but there's not any information on exactly how they interface together so this is only a partial architecture diagram rather than a complete architecture diagram architectures tend to be represented as boxes and arrows diagrams the point of a software architecture diagram is to show the big picture to orient people doing more detailed designs within an architecture diagram the boxes typically represent software modules or objects and the arrows represent interfaces it's important that the diagram actually has meaning that means that each box should have defined semantics it should mean something specific and the same goes for each arrow the meaning of what it means to be a box might change depending on what kind of architectural diagram is being drawn and it might even be that two different boxes have two different meanings what's important is that for each box and arrow on the diagram if you point to a box or you point to a particular arrow you can say this particular arrow means thus and such and this particular box means thus and such as a practical matter that means at a minimum each box and each arrow has some sort of notation with a name rule relationship or other defined term typically a good architecture diagram has all the big ideas on a single letter size sheet of paper with readable font you can push that a little bit but not too much if there's too much to put on one page then you need to define subsystems and encapsulate the complexity inside one box on the top level diagram and then have another diagram nested below that that goes into more detail on that subsystem box there are many different types of architecture diagrams for example a software architecture which might have components and data flows a hardware architecture that shows for example how the software components are allocated to the hardware a controls architecture showing the hierarchical control strategy or a call graph showing the runtime hierarchy of calls that is not an exhaustive list anything that is a boxes and arrows diagram that's talking about how different pieces work together could qualify as an architecture diagram the art is in figuring out which diagrams convey the important essence of your system so the detailed designers remain oriented and understand the big picture uml sequence diagrams can be very handy as a high level design notation let's build up the pieces of a sequence diagram so you can see how they work each sequence diagram has a set of objects at the top of the diagram each object might be a component in the system or an instance of a class of objects and so on the objects have the ability to perform computation and communicate with other objects via messaging subroutine calls sending data what have you each object has a timeline descending from top to bottom when reading this diagram time progresses from top to bottom along the dotted lines the arcs are interactions between objects an arrow that goes from one object to another indicates that the first object is communicated with the second object and the position of the arrow vertically tells you when that happens generally the timeline is not to scale but rather all that really matters is which arrowhead happens before which arrowtail implying that there's a dependency each sequence diagram shows one scenario which we'll get to in a moment there are optional ovals on the timelines ovals at the top are typically preconditions what a precondition means is the following has to be true for this sequence diagram to apply if it's not true it simply means you need to go find a different sequence diagram that has all the preconditions satisfied so you know what's supposed to happen ovals in the middle are typically side effects so there might be event 1 in event 2 in event 3 and event 3 causes a side effect in the far right object where a side effect is a variable assignment producing an output to the real world and so on ovals at the bottom are post conditions those are properties that are true at the completion of the sequence diagram overall a sequence diagram is a partial behavioral description for the interaction among a set of objects there are specific objects that participate the rest you leave out of the diagram and if the preconditions are all satisfied some events occur some side effects may happen and at the end the system is gone from the precondition state to the post condition state what happens next the system finds a different sequence diagram that now has its precondition satisfied and executes ingly in general the operation of a system is a set of invocations of sequence diagrams that have their preconditions met if you have the set of all sequence diagrams designed for a system then that is the behavioral description of how the system behaves overall with each sequence diagram representing a piece of that behavior here's an example sequence diagram for a soda vending machine in this diagram blue represents physical objects not computers and black is microcontrollers with software although that is a non-standard notation pre means precondition post means post condition and other ovals are side effects this sequence diagram is only eligible to execute with the precondition that the coin control controller thinks that there are two coins already in the soda machine nothing happens until the customer on arc 1a presses coin return therefore for this sequence diagram to trigger the preconditions have to be true and the first arc has to occur which is pressing the coin return the coin return button itself sends a pulse to the coin control which dispenses two coins the first one to a 2b which has a side effect of saying all right i used to have two i have one fewer coins now after the side effect coin control tells the van control by the way i only have one coin now because vent control keeps track of what the price of things is coin control dispenses the second coin reduces coin count again and at the end because you started with two coins and coin count has been reduced twice the post condition is guaranteed to be that there are no coins left and the venn control has been told this as well as the coins actually being returned to the customer there are other objects in this system but they're omitted from the diagram because they do not participate in this particular interaction summing up a sequence diagram has a set of objects some preconditions some interactions and side effects and a post condition with that sequence diagram showing one possible way to execute a use case within a system once you have use cases and an architecture defined you need to get from use cases to sequence diagrams to complete high level design let's take a look at how the pieces fit together first there are use cases a use case diagram shows the types of interactions in a system each system has multiple use cases which each correspond to a different way to interact with the system in this example use case number one is inserting a coin into a soda machine for each use case one or more scenarios are defined a scenario is a specific variant of a use case that provides more detail for example you might have inserting a coin to add money or there might be a use case where an extra coin beyond what is necessary is inserted while that is not desired behavior a customer might do it and the machine should do better than simply eating the coin and there might be other scenarios as well all of which have to do with inserting a coin into a soda machine each scenario has preconditions a scenario description and post conditions scenarios are typically written in structured english language plaintext once you've defined the scenarios each scenario is translated directly into a sequence diagram the sequence diagram also has preconditions a number of actions and post conditions translating to a sequence diagram typically involves going from fairly generic set of steps and scenarios step one step two step three to much more precise descriptions of which object is sending what information to what other object typically there's one sequence diagram per scenario but many scenarios per use case and many use cases for the system therefore you'll end up with a big pile of sequence diagrams at the end the next step in detail design is to convert those to state charts we'll take a look at how that happens to make the link more explicit if high level design puts out sequence diagrams and detail design involves state charts how do you get from sequence diagrams to state charts closing that link is done the following way typically there's a huge pile of sequence diagrams for a system figuratively speaking spread them all out on the floor so you can see all of them then decide which object you're interested in pick an object and for every sequence diagram in the system first find the sequence diagrams that actually have that object remember a sequence diagram omits an object if the object doesn't matter so generally speaking only some sequence diagrams will involve any particular object on the sequence diagrams of the object find the object and all the input in output arcs in these diagrams i've drawn red boundaries around to show you what they are look at the object from top to bottom every time an arrow originates or ends in the timeline that arrow counts there may still be quite a number of sequence diagrams and you've identified the object and all its arrows well what does this really mean what it means is you have a number of partial descriptions of object behavior and whatever state chart is there has to account for all those interactions from that synthesize a state chart that has the ability to do all the interactions if you see two input arrows that are the same on different sequence diagrams but produce different behaviors that must mean they're accepted in different internal states and so on there are tools that can help support the synthesis but they can be very picky about requiring absolutely perfect sequence diagrams that think of every eventuality in practice people aren't too bad at this as long as you narrow it down to a state chart for a single object and you iteratively go back and forth between the state chart and sequence diagrams to make sure all the behaviors are accounted for when you're done what needs to be true is that the state chart when executed will always accept the inputs in the sequence diagrams and send the correct outputs so that whichever sequence diagram is active will result in a system behaving the way it's supposed to wrapping up let's take a look at high-level design and architecture best practices the hld document the high-level design document should include one or more architecture diagrams to give you the big picture of the components and their interfaces that might include a hardware architecture software architecture network architecture it might be some all or none of these but at some point if there's no architecture diagram there's no way to be oriented to what the system does the hld should also have sequence diagrams that cover both nominal and off nominal interactions in other words intended behavior but also behavior that deals with exceptional conditions or mistakes made by users and so on there's a fully worked example for a soda machine available in a course archive for 18-649 that goes through the entire v process using the methods described i recommend you take a look at that for concrete examples the hld needs to co-evolve with the requirements you need nouns that's the architecture part and verbs that's the requirements part to define a system if you don't have both pieces then you don't have a way to actually say some component does some behavior as you do state charge you'll find out that the transition between two states is undetermined and that infers a missing hole in the high level design some pitfalls for high level design are diagrams that leave out interactions if you have a diagram that's all boxes and no arrows or the arrows don't mean anything then you need more information to actually understand what's going on some high-level designs have boxes and arrows that do not have well-defined meanings or even play fast and loose with what's a box and what's an arrow another high-level design pitfall is putting too much detail into the hld the hld should still not be saying exactly how you're building the system writing the code rather it should be an exploration of the different interactions between components so that the detailed design of each component can make sure it meets the expectation for those interactions