CSE Software Design and Engineering Jonathan M. Smith 2/13/2001

Administrative lSolaris may not support inet_pton() l266 Moore - dual SCSI boxes a problem for OpenBSD. lSTATUS as of 3AM - things are broken lCode: (but nothing works :-( lHighest priority

Documentation lWhat’s it used for? lWhat forms does it take? lHow does it affect the software lifecycle? lWhat effect does it have on costs? lWhy do people NOT document?

What is documentation for? lInternal memory of what system does - design decisions / tradeoffs - implementation of algorithms - data structures / input formats, etc. lExternal interfaces of system - inputs, outputs, control fields - error-handling conditions

Forms of documentation lManuals / man pages lUser’s Guides lDesign Documents / change-logs lBuilt-in help lComments lCoding rules / object-naming

Manuals and User’s Guides lManuals are precise and complete lUser’s guides are more application- centered lMust focus on external interface lReveal as little about internals as possible (“malloc() badness”)

Design Documents/Change Logs lFocus is on assumptions, justification of choices, description of choices lLevel of detail varies lArchival history of system lChange log details this -Explicit, or CVS/RCS/SCCS lInternals versus Externals

Built-in help lDocumentation as part of program lAdvantage: always there lCan be invoked as exception lMay be as simple as a usage message lCan be associated with error handling

Comments / Coding Rules lSource-embedded documentation -associated with source - not for users (except with open source :-) lBest: Big blocks of description + little notes for anything obscure lCoding rules can help, e.g. variable naming, named constants, etc.

Effect on Software Lifecycle lReduces 1-1 communication lProvides means of rapid “ramp-up” for “trainees” / “newbies” lProvides reference for testing lProvides “memory” for when modification requests occur during maintenance

Effects on Costs lDocumentation more expensive short- term, cheaper long-term -May have separate documentation team lEffects on lifecycle => big savings lAnd, good documentation increases user acceptance and hence income!

Why don’t programmers document? lPersonality types (communications skill deficits, “non-verbal”) lEasier to feel complete when it works lChallenge of keeping documentation up to date with code lDon’t like typing :-)