system and design documentation - york university · 2016-01-06 · dd-6! waterfall model –...
TRANSCRIPT
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 !