▼Software Development
8.11.1.5
    contents    up   

Presenting a Milestone 🔗 ℹ

at least we don't have to obfuscate it before we ship it

Top The presentation of an implementation must (usually) proceed in a top-down fashion. The phrase “top down” means that the presentation starts with a high-level overview and then explains the path to the most complex and most likely-to-be-buggy or ill-designed pieces.

A high-level overview of a major component design involves two major pieces:

  • an explanation of all concepts (from the information world) that require an implementation as a separate component (class, module) and their hierarchical relationship to each other; and

  • a brief listing of the purpose statements of the public functionality of the major component and its major private auxiliaries.

For an example, consider the Maze board component. A proper understanding of its role demands several concepts: the coordinate system; the tiles and their connectors; the direction of entering and exiting a connector; and perhaps how the geometry of a graphically rendered board. One way to explain their relationship is to draw an ASCII diagram in the —Read Me file:

    

    board

      |

      |----> tiles

      |       |

      |       |----> treasures

      |       |

      |       |----> connectors

      |                |

      |                |----> connector entry and exit

      |                         |

      |                         |

      |                         v

      |----> coordinate relative to its dimensions

      |

The public functionality for the game board consists of two functions (methods), which jointly implement the key actions of a turn:
[shift-and-insert
 ; insert ‘t‘ into ‘b‘ after sliding row or column ‘n‘ in direction ‘dir‘;
 ; computes new board ‘nub‘ and the leftover tile ‘nutile‘
 (->i ([b board?] [t tile?] [n natural?] [d Direction?])
      #:pre (b n d) (proper-place? b n d)
      (values (nub board?) (nutile tile?)))]
 
[can-reach?
 #; (can-reach? b f t)
 ; is there a path from ‘f‘ to ‘t‘ on ‘b‘
 (-> board? coordinate? coordinate? boolean?)]
Restating their overall purpose and their individual purpose statements suffices at this point. Note how even though the names of these two functions clearly explain their purpose, having an actual purpose statement written down supports the presentation.

Providing this overview of information-data concepts plus basic functionality gives a panel a chance to reason through the high-level design, exposing gaps or misplaced pieces. It also is the entry point for the second half of the code walk.

Down Once the big picture is understood, the presentation must focus on the difficult parts of the code, the parts that may contain coding bugs.

For this part of the code walk, it is best to lead the panel from the public entry point into the component to the complex code—via a high-level explanation of the path(s) that lead to the code in question. Calls to “boring” (technical term) auxiliaries should never distract the presentation; simply state their purpose and don’t show the code.

In this case, can-reach? itself is an interesting piece of code. Like a component it is a unit of code and deserves an overview followed by details. An overview of a “recursive” search algorithm needs rather little: the purpose has been explained (it is public) so the “how” statement suffices:
; a while-based, worklist algorithm
; follows the "paths" that radiate out from a tile at coordinate ‘from‘
; using a plain-list accumulator to prevent chasing cycles
(define (can-reach? b from to) ...)
Having written down the salient design points again supports the presentation. Here the reviewers immediately see that the function uses a loop with a worklist and an accumulator to prevent looping.

Now it is time to show and explain the code, though again with an emphasis on the call that matters:
#; {[Listof (Cons Coordinate Dir)]}
(define from-exits (tile-key-exits (board-tile-key b from)))
(define worklist0  (map (λ (x) (cons from x)) from-exits))
#; {accumulator [Listof Coordinate]}
(let traverse ([worklist worklist0] [seen '()])
  (match worklist
    ['() #false]
    [(cons (cons (? (λ (here) (equal? to here))) entry) others) #true]
    [(cons (cons here entry) others)
     (define more (where-can-I-go-legally b here entry seen))
     (traverse (append more others) (cons here seen))]))
Since the traverse loop is standard, the key part is the call to where-can-I-go-legally, which delivers the “neighbors.” A presenter highlights this call and chases it.

In contrast to can-reach?, where-can-I-go-legally is a private piece of functionality—but it is still a unit of code. Start with an overview that uses the purpose statement (see below) and the “template” idea (“mapping/for-looping” over the possible exits from this tile and checking the neighbors:
#; {Board Coordinate Dir [Listof Coordinate] -> [Listof (Cons Coordinate Dir)]}
; if an avatar is on ‘here‘ and entered the tile via ‘entry‘ where
; can it go on board ‘b‘ – without re-entering a ‘seen‘ tile
(define (where-can-I-go-legally b here entry seen)
  (for*/list ([n*t {(tile-key-gofrom (board-tile-key b here)) here entry}]
              [nxt (in-value (car n*t))]
              #:when
              (let ([all-exits (tile-key-exits (board-tile-key b nxt))]
                    [exit-here-needs-entry-nxt (cdr n*t)])
                (and
                 (member exit-here-needs-entry-nxt  all-exits)
                 (not (member nxt seen)))))
    n*t))
Try to explain this code snippet; hint tile-keys are connectors.

    contents    up