|
|
|
Mark A. Foltz |
|
MIT Artificial Intelligence Lab |
|
March 1, 2001 |
|
|
|
|
|
|
Legacy code is everywhere (Y2K) |
|
High turnover rates in software teams |
|
Software teams spend a lot of time explaining
code to each other |
|
|
|
|
What: structure |
|
How: behavior |
|
Why: purpose, context |
|
From a designer’s perspective |
|
|
|
|
|
|
|
This is the inverse problem of design |
|
Reverse engineering |
|
|
|
Nobody writes documentation |
|
|
|
Self-documenting: a myth? |
|
Programmers can’t explain their own code |
|
|
|
Software is huge |
|
A popular OS: 35M+ lines of code |
|
|
|
|
|
|
|
|
|
Observe them! |
|
What they say (vocabulary) |
|
How they gesture |
|
What they draw |
|
What they write (documentation) |
|
|
|
What’s missing in the code |
|
Design patterns |
|
|
|
What’s not described |
|
Tacit knowledge |
|
|
|
|
|
Investigation |
|
Dialogue |
|
Simulation |
|
|
|
Documentation |
|
Mapping |
|
|
|
Teaching |
|
Narratives |
|
Examples |
|
|
|
|
|
|
|
|
Provide multiple levels of detail |
|
|
|
Present several aspects of the system |
|
|
|
Not require extraordinary annotations by the
programmer |
|
|
|
Scale with the knowledge available about the
design |
|
|
|
|
|
|
|
|
|
|
|
|
AI: What are methods and representations that
can produce explanations of complex systems? |
|
|
|
Software engineering: How do designers think
about their programs? |
|
|
|
Design rationale: What should documentation be trying to capture? |
|
|
|
|
|
|
|
|
Programmer’s Apprentice (Rich, Waters, et al.,
1986-1990) |
|
Tufte’s Visual Explanations |
|
|
|
|
|
|
|
|
|
|
|
Software diagramming languages (UML) |
|
|
|
|
|
|
|
|
|
Can it generate a natural explanation of a
program of moderate complexity? |
|
I.e. blackjack |
|
|
|
Is the explanation helpful? |
|
versus Javadoc:
the 15 minute showdown |
|
Notes