system and design documentation - york university · 2016-01-06 · dd-6! waterfall model –...

DD-1!

System and Design Documentation!

DD-2!

Waterfall Model – Artifacts Produced!

•  What is produced at each level?!

Needs analysis – requirements!

Architectural design – framework!Detailed design – data, algorithms!

Specification – input/output!

Implementation – program text!Maintenance – corrections, evolution!

DD-3!

Waterfall Model – Artifacts Produced!

•  The artifacts produced are human readable documents!

Needs analysis – requirements!

Architectural design – framework!Detailed design – data, algorithms!

Specification – input/output!

Implementation – program text!Maintenance – corrections, evolution!

DD-4!

Waterfall Model – Artifacts Produced!

•  The artifacts produced are human readable documents!»  They may be formal

– use mathematics and programming languages!

Needs analysis – requirements!

Architectural design – framework!Detailed design – data, algorithms!

Specification – input/output!

Implementation – program text!Maintenance – corrections, evolution!

DD-5!

Waterfall Model – Artifacts Produced!

•  The artifacts produced are human readable documents!»  They may be formal

– use mathematics and programming languages!

»  They may be informal – use natural language!

Needs analysis – requirements!

Architectural design – framework!Detailed design – data, algorithms!

Specification – input/output!

Implementation – program text!Maintenance – corrections, evolution!

DD-6!

Waterfall Model – Artifacts Produced!

•  The artifacts produced are human readable documents!»  They may be formal

– use mathematics and programming languages!

»  They may be informal – use natural language!

»  At all times strive for correctness and precision!

Needs analysis – requirements!

Architectural design – framework!Detailed design – data, algorithms!

Specification – input/output!

Implementation – program text!Maintenance – corrections, evolution!

DD-7!

Principles of Public Design!

•  Principle of Use!

»  Programs will be used by people !

•  Principle of Misuse!

»  Programs will be misused by people !

•  Principle of evolution!

»  Programs will be changed by people !

•  Principle of migration!

»  Programs will be moved to new environments by people!

Why all system documents are human readable

DD-8!

System Documentation Purpose!

•  All system documentation – program text included – are primarily to be read and used by people!

•  Execution is incidental!

Primary purpose of design documentation is to���communicate with other people – even you are���somebody else in the future, so you must���communicate with yourself

DD-9!

Design Document Contents!

•  Documents the structure of the software system at different levels!

»  At a high level shows the !

DD-10!

What is Design?!

DD-11!

What is Design? – 2!

•  The creation of a plan.!

DD-12!

What is Design? – 3!

•  The creation of a plan.!

»  Consider design as imposing constraints on the "when" and "what" of programming.!

DD-13!

What is Design? – 4!

•  The creation of a plan.!

»  Consider design as imposing constraints on the "when" and "what" of programming.!

»  From this perspective, the entire life cycle is comprised of design at various levels . !

DD-14!

What is Design? – 5!

•  The creation of a plan.!

»  Consider design as imposing constraints on the "when" and "what" of programming.!

»  From this perspective, the entire life cycle is comprised of design at various levels . !

>  Design occurs at all the levels of the Waterfall Model from requirements to implementation!

DD-15!

What is Design? – 6!

•  Design comes from the root to designate, to name!

DD-16!

What is Design? – 7!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

DD-17!

What is Design? – 8!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

»  The difficult part is finding the "right" objects and the "right" relationships!

DD-18!

What is Design? – 9!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

»  The difficult part is finding the "right" objects and the "right" relationships!

»  There must be a correspondence between specification and implementation!

DD-19!

What is Design? – 10!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

»  The difficult part is finding the "right" objects and the "right" relationships!

»  There must be a correspondence between specification and implementation!

>  The objects and relationships in the specification must correspond to the objects and relationships in the implementation!

DD-20!

What is Design? – 11!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

»  The difficult part is finding the "right" objects and the "right" relationships!

»  There must be a correspondence between specification and implementation!

>  The objects and relationships in the specification must correspond to the objects and relationships in the implementation!

>  The Direct Mapping Rule!

DD-21!

What is Design? – 12!

•  Design comes from the root to designate, to name!

»  In design one names objects and their relationships!

»  The difficult part is finding the "right" objects and the "right" relationships!

»  There must be a correspondence between specification and implementation!

>  The objects and relationships in the specification must correspond to the objects and relationships in the implementation!

>  The Direct Mapping Rule!>  Purpose of documentation is to show that

correspondence!

DD-22!

Design within the Lifecycle!

•  Consider the constraints imposed in the software lifecycle!

DD-23!

Design within the Lifecycle – 2!

•  Consider the constraints imposed in the software lifecycle!

»  Putting together a requirements document constrains what can be done from all possible programs to the set of programs corresponding to the requirements!

DD-24!

Design within the Lifecycle – 3!

•  Consider the constraints imposed in the software lifecycle!

»  Putting together a requirements document constrains what can be done from all possible programs to the set of programs corresponding to the requirements!

»  The specification formalizes the requirements and in the process adds more constraints.!

DD-25!

Design within the Lifecycle – 4!

•  Consider the constraints imposed in the software lifecycle!

»  Putting together a requirements document constrains what can be done from all possible programs to the set of programs corresponding to the requirements!

»  The specification formalizes the requirements and in the process adds more constraints.!

>  The set of possible programs is smaller!

DD-26!

Design within the Lifecycle – 5!

•  Consider the constraints imposed in the software lifecycle!

»  Putting together a requirements document constrains what can be done from all possible programs to the set of programs corresponding to the requirements!

»  The specification formalizes the requirements and in the process adds more constraints.!

»  Architectural design adds constraints, and so on.!

DD-27!

Design within the Lifecycle – 6!

•  Consider the constraints imposed in the software lifecycle!

»  Putting together a requirements document constrains what can be done from all possible programs to the set of programs corresponding to the requirements!

»  The specification formalizes the requirements and in the process adds more constraints.!

»  Architectural design adds constraints, and so on.!

»  Even implementation (programming) adds constraints by specifying in detail every when and what and so is a part of the design process.!

DD-28!

Design within the Lifecycle – 7!

•  At each stage, there are fewer choices for the what and when in the final program text!

DD-29!

Design within the Lifecycle – 8!

•  At each stage, there are fewer choices for the what and when in the final program text!

•  At each stage the choices must be made within the constraints imposed by the earlier choice!

DD-30!

Design within the Lifecycle – 9!

•  At each stage, there are fewer choices for the what and when in the final program text!

•  At each stage the choices must be made within the constraints imposed by the earlier choices!

»  Or else, backtracking to earlier stages is required!

DD-31!

Design within the Lifecycle – 10!

•  At each stage, there are fewer choices for the what and when in the final program text!

•  At each stage the choices must be made within the constraints imposed by the earlier choices!

»  Or else, backtracking to earlier stages is required!

•  At the end of the implementation stage!

»  All constraints have been specified, no choices remain, there is the complete program text defining a single executable system!

DD-32!

Design Document Contents!

•  Documents the structure of the software system at different levels!

»  At the system level you describe the system as a collection of components!

DD-33!

Design Document Contents!

•  Documents the structure of the software system at different levels!

»  At the system level you describe the system as a collection of components!

»  A high-level of design describes the classes that make up a system component!

DD-34!

Design Document Contents!

•  Documents the structure of the software system at different levels!

»  At the system level you describe the system as a collection of components!

»  A high-level of design describes the classes that make up a system component!

»  A low-level of design describes a class!

DD-35!

Design Document Contents!

•  Documents the structure of the software system at different levels!

»  At the system level you describe the system as a collection of components!

»  A high-level of design describes the classes that make up a system component!

»  A low-level of design describes a class!

»  At the lowest level, other than program text, you describe the algorithms used for non-trivial methods!

DD-36!

Contents for a small system!

•  What are the important classes? !

•  What are the important methods? !

•  How do they interact with each other? !

•  What are important objects that get created at runtime? !

•  How are they connected to each other?!

DD-37!

Audience!

•  Developers!

DD-38!

Audience!

•  Developers!

»  The customer / user never sees the design document !

DD-39!

Audience!

•  Developers!

»  The customer / user never sees the design document!

>  The customer sees the requirements document, the specification document and the user document!

DD-40!

Audience!

•  Developers!

»  The customer / user never sees the design document!

>  The customer sees the requirements document, the specification document and the user document!

>  The user sees the user document!

DD-41!

Documentation Goal!

•  An experienced developer that is unfamiliar with the system should be able to read the documents!

»  To learn and understand the systemʼs design!

»  To know and understand the rationale for the design!

DD-42!

Diagrams are crucial!

•  A design document without diagrams is a poor document!

•  Need at each level!

»  Diagrams that show the objects of interest at that level and how they are structurally related and how they communicate!

>  E.g. at a high-level of design need a diagram showing how classes are related through inheritance and uses, has_a, and part_of relationships!

DD-43!

Diagrams are crucial!

•  A design document without diagrams is a poor document!

•  Need at each level!

»  Diagrams that show the objects of interest at that level and how they are structurally related and how they communicate!

>  E.g. at a high-level of design need a diagram showing how classes are related through inheritance and uses, has_a, and part_of relationships!

>  Sequence diagrams – dynamic model – showing important objects, and when and how they interact at runtime!

DD-44!

Class diagrams!

•  Select the important classes / methods of your system and present the relationships between them in a UML class diagram !

DD-45!

Class diagrams!

•  Select the important classes / methods of your system and present the relationships between them in a UML class diagram!

•  Draw multiple diagrams rather than a single huge one !

DD-46!

Class diagrams!

•  Select the important classes / methods of your system and present the relationships between them in a UML class diagram!

•  Draw multiple diagrams rather than a single huge one!

•  DO NOT show every class in the system and / or every method in each class!

DD-47!

Class diagrams!

•  Select the important classes / methods of your system and present the relationships between them in a UML class diagram!

•  Draw multiple diagrams rather than a single huge one!

•  DO NOT show every class in the system and / or every method in each class!

•  Automatic tools do a poor job of creating class diagrams!

DD-48!

Class diagrams!

•  Select the important classes / methods of your system and present the relationships between them in a UML class diagram!

•  Draw multiple diagrams rather than a single huge one!

•  DO NOT show every class in the system and / or every method in each class!

•  Automatic tools do a poor job of creating class diagrams!

»  Draw your own diagrams!!

DD-49!

Example of a poor class diagram!

DD-50!

Example of a useful class diagram!

DD-51!

Sample sequence diagram!

DD-52!

Learn a diagram tool!

•  As a software engineer, you will often need to create design diagrams !

•  Find a drawing tool that works for you and learn it well !

•  See link to list of tools on course website !