Skip to content

Latest commit

 

History

History
239 lines (165 loc) · 9.43 KB

doc.md

File metadata and controls

239 lines (165 loc) · 9.43 KB

 

 home   |   syllabus   |   groups   |   moodle   |   video   |   review   |   © 2022

Documentation

Tell me a story I can Understand

(that makes me want to use your code)

"I have made this letter longer since I did not have time to make it shorter" -- Blaise Pascal

  • Documentation is hard
  • Doc generation tools are the start, not end, of documentation
  • Badges are “bling” (not documentation)

image

Example of good “why” documentation

Showcases succintly,

  • the key points
  • what the thing is
  • where to learn more?

e.g. Starship

image

Some Documentation Generation tools'

Lightweight (markdown):

image

Heavyweight (latex):

image

(Aside: please take a moment to read the sad, sad story about markdown's creator).

Pdoc3: Python doc strings ⇒ markdown ⇒ web pages

Trans-document documentation tools

So that's it? The Documenation Problem is Solved?

Not really

None of these tools solve the documentation problem

Kinds of doc (hint: "why not"; rarer than "why"; rarer than "how"; rarer than "what"):

For a sensational case study, read the original textbook on "C".

If you want to reap the benefits of good documentation

Make the documents something reasonable

(e.g. documentation ⇒ verification or documentation ⇒ code generation)

“Why not” documentation

  • e.g. Feature model: looks like “just” a pretty picture.
  • But look again: see the logic? the constraints? the why nots

image

  • This model: 10 variables, 8 rules
  • Linux kernel: 6,888 variables, 344000 rules

“What” documentation:

  • e.g. State transition diagrams

  • David Harel, Statecharts: A visual formalism for complex systems. Science of Computer Programming, 8(3):231-274, June 1987. 10,100+ citations (!!!)

  • Black dot = initial state

  • Dashed lines: parallel work

  • Words on arcs: transition guards

  • Solid line: nested sub-state machines (and all transitions on super-states apply to sub-states)

    image

  • Good for scriblling on white board:

    • very good for small systems ( e.g. internal reasoning within one class )

  • Good for reasoning about mission critical kernels on safety critical systems

    • Can reason over diagram to look for
      • Live locks: loops which never terminate
      • Dead locks: states we can never escape

image

“What” documentation

  • e.g. Entity-Relationship Diagrams
  • Database design
    • Don’t document the code
    • Document the data it runs on
  • Everything is tables, whose cells can be String, Number, Date, Blob (binary object), Null, etc...
    • But NOT a nested table
  • If many of these things depends on many of those things
    • Add a relationship table in between
  • A set of sanity checks for “bad” table design
    • Store every datum once, and only once
    • Avoid, add/delete/update anomalies
  • Many tools for auto-application generation (GUI screen Generation, ORMs like Entity Framework [C#], mapping to databases).

image

Documentation ⇒ code generation

e.g. ER diagrams: screen painting tools

Interactive GUIs generated from database table design

image

e.g. State transition diagrams

cross-compile to “C”

image

image

e.g. Compartmental diagrams: Easy to code:

  • Flows change stuff (and stuff is called Stocks).
  • Stocks are real-valued variables , some entity that is accumulated over time by inflows and/or depleted by outflows.

image

image

  • To code CM,

    • sum in + out_flows_ around each stock;
    • multiply that by the time tick dt
    • add the result back to the stock
    • e.g. v.C += dt*(u.q - u.r) (u,v = before,now)

    image

    image

Digression: A little trip into the land of UML

“What” documentation: UML = ER + procedures

  • Unified modeling language

    image

    image

Hints for writing class diagrams

  • Don't add gets/setters to class methods
  • If there is a relationship classX to classY,
    • Don't add variables to X,Y.
    • Instead connect them with a line and label the line.
    • E.g. Professor instructs student
  • Also, consider writing fewer classes (this one will just blow your mind).
    • e.g. Before: 10,000 LOC, 115 modules, 207 classes
      • After: Downsized to 135 LOC, 3 classes (to handle a particular application)
  • Brainstorm with CRC cards
    • Class, responsibility, collaboration cards
      • Walk through specific scenarios
    • Hold the card to your chest and say “I update the X”
    • And when the responsibility feels wrong, pass it to another class

image

History has not been kind to UML

  • UML = under-defined modeling language
    • Not enough semantics to support verification
  • Marian Petre: "UML in practice" ICSE'13, 2013. http://oro.open.ac.uk/35805/
    • UML has been described by some as "the lingua franca of software engineering". Evidence from industry does not necessarily support such endorsements. How exactly is UML being used in industry — if it is? Interviews with 50 professional software engineers in 50 companies
Number
no UML 35
selective 11
auto-code gen 3
retrofit 1
wholehearted 0
Who uses what Number
Class diagrams 7
Sequence diagrams 6
Activity diagrams 6
State machine diagram 3
Use case diagrams 1
  • UML useful for
    • A 'thought tool'
    • For communicating with stakeholders
    • For collaborative dialogs
    • As the starting point for adaptation (i.e., using a homegrown variant of the "real" notation)
  • Two ways to read Petre’14:
    • An indictment: after 20 years, UML is still mostly not used and not valued.
    • More hopefully, parts of UML are used; the more we learn about which ones, where, why, and how, the better our chances of building something better.