Workshop on Distributed Software
Management for e-Science
Day 2 - Software Design
Lecture 3
Early Design
Kostas Kavoussanakis
Principal Consultant, EPCC
Telephone:
Email:
+44 131 650 5021
k.kavoussanakis@epcc.ed.ac.uk
Lecture Overview
4Early design
– what you do before you start coding and why it’s important
4Three main activities
– requirements capture
– functionality design
– system design
4Describing designs
– tricky problem
– text, pictures, formal diagram techniques e.g. UML
4Conclusions
2
1
Software Design Phases Revisited
4Want to make sure that the ‘last design before
coding’ is a good one
Code & Design
Early Design
no design
last design
(before coding)
final item
3
The Design Cube Revisited
Early Design
good final item
intersection
Code & Design
last design
before coding
ta
de
no design
il
merit
4
2
Early Design
4What happens if the last design before coding is
poor or non-existent?
– you’ll be coding without a clear idea of what you’re trying to
achieve and why and how
– you’ll be moving to fiddly detail before getting the basics sorted
• you’ll be trying to add carpets before you’ve got foundations
– you’ll hit problems continuously, and fixing them will be costly
• re-writing code is much more expensive than changing a sentence in
a design document
– everything will take longer and the outcome will be poorer
– your chances of success, fulfillment and happiness will be low
5
The Design Cube Revisited
Early Design
intersection
Code & Design
hopeless final item
ta
de
il
last design before coding
no design
merit
6
3
Software Design Phases Revisited
Code & Design
Early Design
no design
Requirements
Capture
last design
(before coding)
Functionality
Design
System
Design
final item
Code
Design
Final
Test
7
Early Design
41. Requirements Capture
– “what exactly is the problem we’re trying to solve?”
– analyse the problem and establish the design goals
– results in a requirements document
42. Functionality Design
– “what’s the solution going to do?”
– functionality and user interface
– results in a functional specification document
43. System Design
– “how’s it going to do it?”
– system architecture and detailed design to some level
– results in a system design document
8
4
Document Production
4The outcome of each of these phases is a
document
– “Aarrgghh, I hate writing documents - I’m a programmer!”
– no need to panic
4The length of these documents should be
proportional to the size of the project
– half a page each may be enough for a (very) small project
4But every project should have them in some form
– the benefits of knowing what you’re trying to achieve beforehand
cannot be overestimated!
9
1. Requirements Capture
4“What exactly is the problem we’re trying to solve?”
4Aim to produce a Requirements document
including:
– a statement of what you believe the problem is
– basic functional goals
• a list of what the software must do
– additional functional goals
• a prioritised list of any secondary requirements or enhancements
– performance goals
• any requirements on how the software must perform
10
5
Obtaining Information
4Who is your ‘customer’?
–
–
–
–
–
external organisation
internal department
funding body
research colleague
focus on whoever gives the ‘thumbs-up’ at the end
4Use all appropriate means to probe for accurate
detailed information about the problem
–
–
–
–
face to face discussions
observation of existing system (if any)
study of existing documentation (if any)
questionnaires
11
The Unreliable Narrator
4Customers are like unreliable narrators in novels
– you may get a mixture of truths, half-truths and outright falsehoods!
– you may get conflicting information
• particularly when several people have a say
– information may be withheld (inadvertently or otherwise)
4But if the software solves the wrong problem, the
customer will blame you!
4So try to untangle the requirements mess as early
as possible
– probe into the dark corners
– overturn the stones
12
6
Cans of Worms
4Retailer: “I want a simple program to print out
reports of all my current stock”
–
–
–
–
–
–
–
–
what's the input data?
how's it going to be entered? manually? bar-code swiping?
how is the stock data to be stored?
what sort of reports do you want? sorted? grouped?
how often do you want them generated?
what if it takes 5 minutes to generate? is that too long?
do you really mean print to a printer or to the screen?
what if there are reams and reams of it?
13
The Underlying Problem
4The customer’s perception of the problem may
not reflect the real underlying problem!
– what the retailer really wanted to know was "Do I have a TX354-2
out the back?"
– he was going to manually scan through the list of stock until he
came to TX354-2 in the part number column
– the underlying problem was the ability to query a stock database
4Need to understand the underlying business or
technical problem that needs to be solved
14
7
Requirements Summary
4Gather the information you need
4Resolve conflicts and inconsistencies
– beware that some requirements may not actually be feasible
• for technical or time and budget reasons
– may have to negotiate a relaxation of certain requirements
4Write a clear and concise Requirements document
4Seek the customer’s approval of the document
before proceeding
15
2. Functionality Design
4“What’s the solution going to do?”
– design the behaviour of a system which would satisfy the requirements
– propose a software solution without worrying unduly (yet) about how to
build it
4Aim to produce a Functional Specification document
including:
– the main features of the user interface
• and how the user will interact with the UI to achieve their tasks (use cases)
– the input data
• and how the system will modify it
– the main functionality
• and how it will operate on the data in order to satisfy the requirements
16
8
User Interface Design
4Different user interfaces for different applications
– the software may have a command-line or parameter file UI
– more commonly nowadays it will have a graphical ‘Windows style’ UI
4Designing the main features of the UI early on is
highly recommended
– gives everyone a picture of the final item
– focuses the development team on a common target
4UI prototyping
–
–
–
–
dialog diagrams are helpful but interactive prototypes are better
e.g. can use Tcl/Tk, VisualBasic etc. to create UI prototypes quickly
add connections between the dialogs and some fixed ‘dummy data’
but leave the underlying functionality unimplemented
17
User Interface Design
4May have to cater for different types of users
– novice users may want to be hand-held through it
– expert users usually want to whiz through it with as few mouse
clicks as possible
4UI conventions have evolved over the years
– use them!
– e.g. see Microsoft’s Windows Interface
Guidelines for Software Design
– saves you time as well as preventing nasty surprises for the user
4Save your originality for devising intuitive ways of
displaying data specific to your application domain
18
9
Use Cases
4How will the main functions be accessed from the
user interface?
4Use cases (in the formal or informal sense) can be
very helpful
– for clarifying your own ideas about how the system will behave
– for describing to the customer how it will behave
4For each of the main tasks that the user can
achieve with your software:
– show the sequence of interactions they will have to make with the UI
to achieve that task
– show what happens to their data (files) on the way
19
Emphasis on Data
4In general, customers understand their data
– it’s important and precious to them
4So communicate with them in terms of things
they understand
4Show them:
–
–
–
–
what you think their data is
what you’re going to do to their data
what new data you’ll leave them with at the end of the day
what hoops they’ll have to jump through to get it
4And they’ll tell you if it’s a system they want
20
10
Main Functions
4What are the main functions of the system?
4For each main function describe the following:
– its behaviour
– its input and output data
– how the data is modified by the function
4Use pictures and examples wherever possible
– saves lots of typing, aids understanding
– e.g. a “dog-leg removal” function in a chip layout program
21
Design Evolution Revisited
4Designing involves two main things:
– 1. having ideas
– 2. realising they’re rubbish (and why they’re rubbish)
4Iterative refinement
– try not to fall in love with your first idea
– through perseverance and cunning you may come up with a
valuable simplification
4Encourage ‘off the wall’ thinking
– brainstorm with colleagues
• look for new angles on the problem even if they seem silly at first
• don’t evaluate the ideas until end of the session
– good times for solo inspiration?
• on the toilet and just before going to sleep can be surprisingly good(!)
22
11
Design Evaluation Revisited
4Detail
– have you described the functionality in sufficient detail for it to be
meaningful?
– “and there will be a graphical user interface” is not sufficient detail!
4Intersection
– will the functionality that you’ve described satisfy the design goals?
– does your functionality solve the right problem?
– is the functionality consistent and coherent?
4Merit
– does the behaviour you’ve described have desirable properties?
– is the system as simple as possible?
– is it intuitive?
23
Design Evaluation
4Probing to the next level of detail beyond the level
you’re documenting can be very useful
– helps establish the quality of what you are documenting
4E.g. “the interpolation facility will operate on the
curve data which is passed in”
– sounds fine
– but on probing to the next level of detail you discover that the
interpolation facility also needs a point at which to interpolate the
curve
– where’s this point going to come from?
– oops - inconsistency exposed
– much cheaper to fix it sooner than later
24
12
Functional Design Summary
4Design the behaviour of your solution
– and prototype the user interface if possible
4Iteratively evolve and improve the design
– focus on the critical features first
4Try to gain confidence in its quality
– evaluate it and get someone else to review it
4Write a clear and concise Functional Specification
document describing it
4Again seek document approval from the customer
25
Practicalities
4Unfortunately, the functional spec could be a lot
bigger than the requirements document
– if it’s more than 30 pages you may have trouble getting it read at all
– “I’ve already given you the requirements, it’s your job to build the
system so it satisfies them”
4It’s a trade-off between detail and practicalities
– make sure that what detail you have adds value
– emphasise the data so the customer has a direct interest
– put the UI description and use cases towards the front
• for some reason everyone has an opinion on user interfaces!
26
13
3. System Design
4“How’s the solution going to work?”
– how will the documented behaviour be realised in software?
4Aim to produce a System Design document
including:
– system architecture
• how the system will be composed of smaller components or modules
– component descriptions
• responsibilities and interfaces
• where will the main functions reside?
• main data structures and algorithms
– solutions to key technical problems
– enough detail that moving to code doesn’t seem like a huge step!
27
System Architecture
4‘Top-down’ approach is common
– split the system into components or modules
•
•
•
•
user interface
database
core functionality
options package etc.
– split the components into sub-components and so on
4Identify the interdependencies between the
different components
– try to group data and functionality so as to keep dependencies
across component boundaries to a minimum
28
14
Components
4Why has this component been defined?
– what’s its purpose?
– ensure the component has clear goals and responsibilities
4Which of the component’s functions will form the
interface to the outside world?
4Which of the main functions will reside in this
component?
29
Components
4How will the component’s data be modeled in
software?
–
–
–
–
arrays, records, structs, objects?
what will they contain?
what’s the lifetime of the data?
who’s responsible for the creation / destruction of which data?
4What are the main algorithms and how will they
be implemented?
– give pseudo-code if appropriate
– pseudo-code shouldn’t just be verbose normal code!
– it should capture the essence of the algorithm, but omit unhelpful
detail
30
15
Pseudo-Code Example
4Graphics update algorithm
for each open window, w {
for each of w’s objects, obj {
if obj has been modified since last redraw then {
redraw obj
clear obj’s modified flag
}
}
}
31
When to Stop?
4When should you stop documenting the system
design and actually start coding?
– tricky matter of judgement
4Things to ask yourself to see if you’re ready
– are there any parts of the design I’m particularly nervous about?
– is my vision of the system the same as that of my co-developers?
– is there enough design detail for coding to be an orderly guided
activity?
– do I think I’m close enough to the top-right corner of the design cube?
4Often worth going to pseudo-code detail for trickier
areas first
– quicker than writing and compiling real code
32
16
System Design Summary
4Design the architecture of the system
4Design the components and their interactions
4Evolve and improve the design
4Check it relates closely to the Functional Spec
4Write a clear and concise System Design document
4Unlike the Requirements and Functionality
documents, this is an internal document
– for the benefit of the developers when they start coding in earnest
– customer doesn’t care how it works as long as it does work
33
Keeping Documents Alive
4For some projects documents quickly ‘die’
– they are written, looked at initially, then forgotten
4Often worth investing time updating new revisions
as the project progresses
4Don’t bother adding large amounts of new detail
– the document size will become unmanageable
– the detail will be documented in the code after all (won’t it!)
4But try to keep them reflecting reality
– reap rewards when someone new joins the team or someone else
has to maintain the system
– valuable history of how the requirements, functionality and system
design developed over time
34
17
Describing Designs
4The result of these three phases are documents
which capture some aspect of design
4But designs can be large and involved
– difficult to describe concisely and consistently
– this is a serious problem for many projects
4What are the options for describing a design?
– text
– pictures and diagrams
– formal diagram techniques
35
Text Descriptions
4Potentially the most expressive and accurate
technique
4But also the least concise
– regardless of how good your design is, no one will want to read
about it if it takes 50 pages to describe it
4Difficult to maintain self-consistency
– if a paragraph on page 2 contradicts a statement on page 345, is
anyone really going to spot it?
– if you change something on page 49, how are you supposed to
identify the other pages that should change as a result?
36
18
Text Descriptions
4Employ the obvious ‘do’s of technical writing
– decompose the document into sections and subsections
– use short sentences
• no excerpts from ‘Yes Minister’ please
– use short paragraphs
• e.g. <= 7 lines
– use bulleted lists for clarity
– use section references to avoid duplicating information
• perhaps use HTML instead of Word to facilitate following references?
– read what you’ve written!
– could you convey the same information in fewer lines?
– have you just written 2 pages of rambling text which could be
captured perfectly using a half-page picture?
37
Pictures and Diagrams
4The old proverb about saving a
thousand words still rings true
4People are much more willing to
study pictures than text
4Modern document processing packages allow
relatively quick diagram production
– Microsoft Word, Framemaker
– definitely worth learning how to use them
4Scope for confusion though
– the reader may not interpret your picture the way you intended
38
19
Formal Diagram Techniques
4Various techniques have evolved in recent decades
– an attempt to capture design aspects more precisely and concisely
than textual descriptions
4Effectively they are visual languages
– if everyone interprets a language in the same way then design ideas
can be communicated accurately and concisely
4Well-defined semantics
– computers can help in diagram production and consistency checking
– some tools generate skeleton code from the diagrams
4Use them to describe designs to yourself/your team
– don’t expect customers to understand them
39
Formal Diagram Techniques
4Older ones from Structured Systems Analysis
– Data Flow Diagrams (DFD)
• for the transfer of data in and out of program units
– Control Flow Diagrams (CFD)
• for algorithms
– Entity-Relationship Diagrams (ERD)
• for the associations between pieces of data in a database
4Newer ones from Object-Oriented Analysis
– Object Modeling Technique (OMT)
– Unified Modeling Language (UML)
4UML
– various diagram types to capture different aspects of a system
40
20
UML Diagram Types
4Class diagrams
– shows static structure of the system’s data entities (classes) and
how they relate to each other
– bit like entity-relationship diagrams
4Object diagrams (or instance diagrams)
– example snapshot of the system’s data (objects / instances) at
runtime
– “limited use, just examples”
– very useful for understanding!
4Various others:
– use case diagrams, sequence diagrams, collaboration diagrams,
state diagrams etc.
41
UML Class Diagram
4Solar system example
HeavenlyBody
SolarSystem
name: String
1
1
name: String
mass: Float
diameter: Float
0..*
Planet
hasLife: Boolean
0..* orbits
1
Star
brightness: Float
1
42
21
UML Object (Instance) Diagram
4Solar system example
:SolarSystem
name = “Our one”
:Planet
:Star
name = “The Sun”
mass = 9354593
diameter = 15238
brightness = 670.34
name = “Mercury”
mass = 64956
diameter = 2534
hasLife = False
orbits
:Planet
:Planet
name = “Earth”
mass = 1425665
diameter = 4532
hasLife = True
name = “Venus”
mass = 1364353
diameter = 3856
hasLife = False
orbits
orbits
43
Conclusions
4Having a good design before coding gives you a
much better chance of success
4Three main activities in Early Design
– requirements capture
– functionality design
– system design
4Describing designs is difficult
– use well-written concise text
– lots of pictures and examples
– consider a formal diagram technique such as UML
44
22
References
4For UI conventions:
– The Windows Interface Guidelines for Software Design, Microsoft
Press
4For UML:
– Si Alhir, S., UML in a Nutshell, 1998, O'Reilly & Associates
– Page-Jones, M., Fundamentals of Object-Oriented Design in
UML, 2000, Addison-Wesley
45
23