1 Maintenance of Documentation and Documentation of Maintenance Quiz 7 Tori Bowman CSSE 375, Rose-Hulman October 1, 2006.

11

Maintenance of Documentation Maintenance of Documentation and Documentation of and Documentation of

MaintenanceMaintenance

Quiz 7Quiz 7

Tori BowmanTori BowmanCSSE 375, Rose-HulmanCSSE 375, Rose-Hulman

October 1, 2006October 1, 2006

State of 375State of 375

• HW 4 due 11:55 pm tonight Oct. 8thHW 4 due 11:55 pm tonight Oct. 8th

• Test Review tomorrowTest Review tomorrow– Test 1: October 3Test 1: October 3rdrd from 7pm-9pm from 7pm-9pm

• Thursday: Final maintenance report; Thursday: Final maintenance report; transitiontransition

22

33

ReferencesReferences

• Chapter 11 of SW MaintenanceChapter 11 of SW Maintenance

• Chapter 32 of Code CompleteChapter 32 of Code Complete

44

OutlineOutline

• Maintenance of DocumentationMaintenance of Documentation• Documentation of MaintenanceDocumentation of Maintenance

55

Maintenance of DocumentationMaintenance of Documentation

66

Technical vs. User Technical vs. User DocumentationDocumentation

• Technical documentation involves artifacts Technical documentation involves artifacts used by software developers and maintainersused by software developers and maintainers

• ExamplesExamples– Design DocumentDesign Document– Quality Assurance Data (through metrics)Quality Assurance Data (through metrics)– Maintenance RequestsMaintenance Requests– Most of this lecture: code documentationMost of this lecture: code documentation

• User Documentation will be discussed in later User Documentation will be discussed in later classesclasses

77

What does this even do?!

88

…self-documenting code

Kinds commentsKinds comments

• Repeat of the codeRepeat of the code– Gives the reader Gives the reader

more to read w/o more to read w/o being value-addedbeing value-added

• Explanation of the Explanation of the codecode– If the code is so If the code is so

complicated that it complicated that it needs to be needs to be explained – rewrite itexplained – rewrite it

• Marker in the codeMarker in the code– To-do, ********NOT To-do, ********NOT

DONEDONE

• Summary of the codeSummary of the code– Especially helpful in Especially helpful in

maintenancemaintenance

• Description of code’s Description of code’s intentintent

• Information that can’t Information that can’t be expressed in codebe expressed in code

99

Tips for commenting Tips for commenting efficientlyefficiently• Use styles that don’t break down or discourage Use styles that don’t break down or discourage

modificationmodification– Example on following slidesExample on following slides

• Use pseudo code programmingUse pseudo code programming

• Integrate commenting into your development styleIntegrate commenting into your development style– Make this apart of your coding standards!Make this apart of your coding standards!

• Performance is Performance is notnot a good reason to avoid a good reason to avoid commentingcommenting

• IBM study: 1 comment for every 10 lines of codeIBM study: 1 comment for every 10 lines of code

1010

Comic of the day….Comic of the day….

1111

1212

1313

1414

Don’t comment tricky code; rewrite it!

1515Check out Doxygen: www.doxygen.org/

1616

Documentation of Maintenance Documentation of Maintenance

1717

Some Additional Some Additional Documentation Needed for Documentation Needed for MaintenanceMaintenance• Some Depend on Maintenance Some Depend on Maintenance

Process UsedProcess Used

• ExampleExample– Maintenance PlanMaintenance Plan– Delta Vision DocumentsDelta Vision Documents– Requests for ChangeRequests for Change

•How to use within process?How to use within process?

22ndnd Comic of the Day…. Comic of the Day….

1818

1919

Documentation for our Documentation for our Maintenance ProjectsMaintenance Projects

• Maintenance PlanMaintenance Plan

• Maintenance Project PlanMaintenance Project Plan

• Software ManualSoftware Manual

• Transition PlanTransition Plan

QUESTIONS?QUESTIONS?

2020