COMP2110/2510 Software Design 2008

An example ! the game of Tetris

Lecture Design-6 Documenting Detailed Design

"
How to write down detailed design.
"
Good enough that you can let someone else
implement it.
" This is very hard to do well!
Topics:
" operation specifications shot 1
" Interfaces
" Contracts ! part of the interface
" Internals
" Pseudocode

ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 1 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 2

[demo Tetris
program execution]

ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 3 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 4
 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 5 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 6

1. Operation Specifications Fox section 14.2 2. identification and signature

" "#$%&'"##()&*+(&,-.*(/0"'(1&&*%&*+(&%2(/"*-%.&! publicly visible

" identification " !"#$%&'%()$%&*!+!,%-."//%&0% !"#$%&&
#&12.$ '(#)*+(',-,./0#1/ 1,234*#1/ 1,2567

" signature " !"#$3%4"0"#$($0/3%(54$ " This is not the Java interface concept ! i.e. not a purely abstract
class with no implementation
" description " *)"(%+(%1&$/%! 0$/4&!/+6+.+(5
" This is also not about user interfaces
" behaviour " *)"(%+(%1&$/%+!%1$("+.
" This is about documenting the way a software component interacts
" describe implementation " &4(+&!".%! )&*%+(%-&2.1%1&%+( with other components ! what the programmer needs to know to
write a call

" ,#$%&'()*&+,-.-+&&-)/+0-102-345564---
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 7 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 8
Class signature Routine signature

" List all public (externally visible) features " The information a client (caller) needs
" Members & methods !"#$%
!"#$%&' " What the routine does, not how it does it
" Attributes & routines

}
()*+,)-.&' " Name (well-chosen)
" Queries & commands ()*+/+01&' " Return type Signature
" add info compared to UML class diagram box 234/3.5+5&'
" Argument types and names
!"#$$ !"#$% " Roles of arguments
%&'#()#&* +*+"678"#$%7#47-#12#.712+79:36#.;!)3"5
" One line description: purpose or effect
+),&#*-(. *)#57()*+/+01&#.17.+-<=7#.17.+->'
" Contract: pre and post conditions?
/.$0()1*)2& 1"671)7()*+712#478"#$%7).+79:3$+71)7:+017).712+78)3"5
3.4#')2-( 1(.?7!"#$%%&'()$*'$(+,
" Best generated by tools from comments
12$*?779)4#1#).7#47@.$23.;+57-* embedded into the source code e.g. Javadoc
&9)4#1#).7#47&.+-<=7.+->'7$(.&8"#$%7#47#.712+78)3"5
$(.&8"#$%75)+47.)17)*+":3973.67)12+"71#:+'
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 9 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 10

3. Responsibility & Behaviour: Contracts the contract ! pre and post conditions
class brick
" see Fox: pp 441-446 public void moveLeft (int newX, int newY) 2&3*,(1%"
Contracts, Assertions, Invariants move this brick one tile left, unless !"#$%&'(&)*

" also Meyer Object-Oriented Software obstructed by the edge or an existing tile
Construction Chapter 11 (p.331ff) pre: brick is within board (the class invariant) +)*(%,$(-
post: brick is within board AND )%-
" The idea of invariants, pre- and post- ."/,0&)1%
( position of every tile of the brick is one space
conditions come from formal verification ! can
to the left i.e. a (smaller X coordinate),
lead to formal correctness proofs OR position of every tile is unchanged )
" useful for better design and programs even if (0')//-7.%#/&-#$-8.9'#*:-;7<42-=-742-->?-@-;7<42-=-742?
concern for correctness does not go that far (0')//-7.%#/&-#$-849'#*:-;7<4A-=-74A?
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 11 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 12
Pre- and Post-conditions How strong should preconditions be?

" Precondition: What the routine assumes to be " Too many / too strong
true before it starts " BID+%0E&'-#+-)/F)A+-F'0$J,
" Postcondition: What the routine guarantees to " Routine can't be used
be true when it returns " Too few / too weak
" BID+%0E&'-#+-)/F)A+-'#JG%,
" Contract: { pre } body { post }
" Writing the routine becomes impossible

BC(-A0D-3'0E#+&-%0-*)//-E&-F#%G-EA-3'&*0$H#%#0$+ Guidelines for writing preconditions:

satisfied, then I promise to deliver you a final state
" Must appear in documentation for client code
#$-FG#*G-EA-30+%*0$H#%#0$+-)'&-+)%#+(#&H4,
" Must be justifiable from the requirements

ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 13 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 14

Class invariants ! an internal property of the

Contracts as documentation
class see Fox pp443-445

" Add to the less formal description given as " Global properties of the class
part of the interface " Must be satisfied by every instance at all times
(except possibly while an operation is actually being
" Major benefit is to remove duplication: executed)
" Supplier does not have to check that the " e.g for a stack implementation with an
precondition has been satisfied. (That's the implementation attribute called count
client's job.) inv: count >= 0
" Client does not have to check that the -- note: count is not necessarily visible outside the stack
class
postcondition has been satisfied. (That's the
supplier's job.) " Creation routine must establish invariant
" The full contract is now:
{ pre and inv } body { post and inv }
(There are also loop invariants and variants: see notes for COMP1110 and COMP2100)
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 15 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 16
 4. Internals or Implementation description:
Internals ! class invariants
Pseudocode

" Fox refers to Algorithms and Data Structure

Specification section 14.3 page 448
$:34478"#$%
internals " Pseudocode is one way to describe an algorithm,
'()$*'$(+?712+78"#$%7#479)4#1#).+57-#1273::71#:+47 halfway between natural language and computer
-#12#.712+78)3"573.5 code
-#127.)71#:+47)*+":399#.;73.67)12+"71#:+
AB712+78"#$%7#47:3.5+5 " use indenting and informal control structures
" do not use technical language
'()$*'$(+/ 3::71#:+47)07378"#$%723*+712+743(+7
" do not use details from the implementation language
$):)@" (In other words, the same pseudocode should work for
" Eiffel or Java or C++ or Smalltalk
" C or Pascal or Fortran or Ada
" Bash or Perl or Python or Csh
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 17 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 18

How to write pseudocode pseudocode example - moveLeft

" Break down the body of the routine into steps +(',-,./0#1/*1,234*#1/*1,256&
" Write at the level of intent ,"89,*/:#9*;"#$%*."(+*/:,*<=8>#1?!(8")7
" 3*-##&,4+"*1&.%*&,5%61&78*&"*&"&#%6(/&#(9(#&%0& #.*/:#9*;"#$%*.#/9*(1*/:,*;(8")*8/*01,234*
abstraction 1,256*2#/:*1(*(',"=8<9*/:,1
" Must be at a higher level of abstraction than <=8$,*/:#9*;"#$%*8/*01,2341,256
the finished code ,=9,
" Big idea: The pseudocode becomes the ",<=8$,*/:#9*;"#$%*8/*0(=)34*(=)56
comments in the finished code. ,1)#.
",)#9<=8>*/:,*;(8")

ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 19 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 20
 Merge Sort algorithm Example: pseudocode for the Merge sort
sort: algorithm
list of data - unsorted

if the list has more than one element then

split
divide the list into two equal parts
half list A unsorted half list B unsorted merge sort the first part
merge sort the second part
sort sort while both halves are non-empty do
half list A sorted half list B sorted compare their first elements and select the smaller
end while
merge copy the remaining elements
end if
fully sorted list
ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 21 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 22

Good and bad pseudocode (From Steve McConnell: More on good pseudocode (and comments)
Code Complete)

Increment resource number by 1 Keep track of number of resources in " Think of comments (lines of pseudocode) as
use
allocate a dlg struct using malloc
If another resource is available then
paragraph headings in the finished code
if malloc returns NULL then return 1
invoke Osrsrc_init to initialise a
Allocate a resource structure " Focus on what and why, not how
If a dialog box structure could be
resource for the operating allocated then " Don't just repeat what the code does
system
Note that one more resource is
set *hRsrcPtr equal to resource in use " Always write at the level of intent, not at the level of
number Initialise the resource implementation
return 0 Store the resource number
end if " Write at a sufficiently low level that writing the code
end if itself will be almost automatic for a skilled
return True if a new resource was programmer with little knowledge of the system or its
BAD created, otherwise return False
design (a code monkey ! )

ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 23 ANU COMP2110 Software Design in 2008 Lecture Design-6 Slide 24