11 The Team
26 September 2024
Questions?
11.1 Background
What’s the goal: find flaws, receive negative feedback
No sandwich.
How to set up a panel? 1 + 1 on 3. Why? (IBM, Bell Labs, NASA)
11.2 Presenting
The goal is to present the design and implementation of a project component, hoping to get negative feedback on
the general design
the complex, likely faulty pieces of code
What is a (top-down) overview? What is not an overview?
It is a birds-eye view of the project at this stage, with a focus on the most recent milestone. Amazing developers can deliver it orally; average developers like myself need diagrams, ideally included in a README file. (ASCII diagrams, napkin doodles scanned in, etc.)
An overview concludes with a goal statement, listing the pieces of functionality that need comments from the panelists.
How do Structural Diagrams Help?
A structural diagram explains the static relationships among components and within components (as needed).
Example:
Qwirkle is board game that asks players to compose a game map from tiles that
have a color and a shape on them—
A presenter can also explain how the desired functionality is allocated within these components and classes.
How do Dynamic Diagrams Help?
We may need to show an example sequence diagram.
A dynamic diagram explains the run-time order in which objects are created, in which methods talk to each other. They establish what holds when people inspect a piece of functionality.
It can also bring across how the control flow gets to the point in the code that we want to inspect for problems.
Example: Suppose you want to monitor events inside a process to make sure that they satisfy some constraints, say “open, read often, check eof, close.” Then you can use an Observer pattern, which you know from F III. You should document the dynamic relationship between the process and the observer so that people get a quick idea of what’s happening:
Context
|
| new
O o = | ---> Monitor
| |
| |
| |
| |
| |
| | new(O)
| ---------_----------------------> Process
| | |
| | | %% event e1 happens
| | inform(e1) |
| | <------------------------- |
. . .
. . .
. . .
. . .
. . .
| | | %% event e2 happens
| | inform(e2) |
| | <------------------------- |
| | |
| | done() | %% no more events will happen
| | <------------------------- |
| | |
| ---- the monitor shuts down |
| |
Figure 2: An example of a README diagram of dynamic relationships
What is an Overview for an Interface? A Class? A Method?
Each interface/class/method is a unit of code.
Each of these must have a purpose statement or an incredibly good name that brings across its purpose.
Each of these has structure: three fields, four methods, five tasks.
Start with explaining those without pointing to specific lines.
State up front whether the method is composite and what it composes or whether it is atomic and what its one and only task is
Follow the Design Recipe for Methods
step 2: explain the signatures, the meaning of each parameter?
step 3: a complex method (say strategy) may need a worked example in comments?
step 4: understand the purpose of a ‘for‘, ‘while‘ loop; ‘recursion‘
the accumulators may need ’invariant statements’step 5: explain each line now and only now
step 6: unit tests may help understand the workings of a method
or it can play the role of a worked example
11.3 Paneling
11.3.1 How to Ask Questions
good |
| bad |
How does this function account for the special case of 0? |
| How do you deal with 0 in this function? |
Why does this class come with getters for all fields? |
| Why did you introduce getters for all fields? |
Where does the exception get caught? |
| Where do you catch the exception? |
11.3.2 The Goal
The goal is to discover the following kids of problems:
plain readability
bugs as in contradictions to the spec
design flaws
11.3.3 Questioning What Is Presented
How to Question an Overview?
If the presenter does not present a structural and/or dynamic overview, push back and ask
which classes make up the component?
what’s their purpose in the context of this project?
how do they relate?
is there a README file that explains these things?
How to Question a Structural Diagram?
do the arrows make sense? : is-a arrows (extends, implements), has-a arrows (fields, collection)
are two (or more) concepts represented in the same class?
are there too many/too few interfaces?
are there commonalities in is-a related classes that deserve an abstract class?
is there an abstract class for a single concrete class? Why?
How to Question a Dynamic Diagram?
does the order of object creation make sense?
does the order of calls make sense relative to the spec?
is the order critical? If so, is it checked in code?
what conditions are set up by one call? several calls in a row?
imagine an imperative protocol for the game: ‘setup‘ is needed to enable ‘take-turn‘
Keep the answers in mind for the inspection of code.
How to Challenge an Interface/Class/Method Overview?
what is the purpose of an interface for a single class?
The only reason is that it serves as an interface to the entire component.
Which client components need the interface?what is the purpose of a method?
if the name is clear, it counts against you.- for a long method:
which tasks does this method accomplish?
which data flows from one to the other?
DONT "why is it so long"
Does the Code Respect the Design (Recipe) Rules
Is it composite or atomic?
what does the parameter mean with respect to the specification?
if the method is complex, is there a worked example?
the method is searching a tree (of possible game moves)?
why is it using a ‘while‘ loop?dont ask "WHY is this like that?"
stop the presentation and read the code; that’s your purposeif the results are unclear, ask for exemplary unit tests
if the unit tests play the role of worked example, have the presenter explain them carefully
Total: 60 mins