Skip to content

Latest commit

 

History

History
248 lines (175 loc) · 9.41 KB

doc.md

File metadata and controls

248 lines (175 loc) · 9.41 KB

 home :: syllabus :: timetable :: groups :: moodle :: video :: © 2021

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

image

Example of good “why” documentation

Can you see quickly,

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

e.g. Starship

image

Some Doc Generation tools'

Lightweight (markdown):

image

Heavyweight (latex):

image

(Aside: please take a moment to read the sad, sad story abut the invenvtor markdown).

Pdoc3: Python doc strings ⇒ markdown ⇒ web pages

Trans-document documentation tools

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

Not really

None of these tools solve the documentation problem

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

-what : point description

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

If you want to reap the

benefit of good documentation

Make the documents something reasonable (e.g. documentation ⇒ verification or documentation ⇒ code generation)

“Why not” documentation

  • e.g. Feature model: look 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 readoning about r mission critical kernels of safety critical systems

    • Can reason over diagram to look for
      • Live lock: 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
    • 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 once only
    • Avoid, add/ delete/ update anomalies
  • Many tools for auto-application generation (GUI screen Generation, 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 if with a 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 aprticular applciation)
  • 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.