Download presentation
Presentation is loading. Please wait.
1
CSE 350 - Software Design and Engineering Jonathan M. Smith http://www.cis.upenn.edu/~jms 2/13/2001
2
Administrative lSolaris may not support inet_pton() l266 Moore - dual SCSI boxes a problem for OpenBSD. lSTATUS as of 3AM - things are broken lCode: 14253 (but nothing works :-( lHighest priority
3
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?
4
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
5
Forms of documentation lManuals / man pages lUser’s Guides lDesign Documents / change-logs lBuilt-in help lComments lCoding rules / object-naming
6
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”)
7
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
8
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
9
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.
10
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
11
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!
12
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 :-)
Similar presentations
© 2024 SlidePlayer.com Inc.
All rights reserved.