Systems Engineering. Analyse. Design. Implement. Delivery of product. Test. Time

Transcription

1 RobinSharp SoftwareDevelopmentProjects DepartmentofInformationTechnology,DTU September2000 JensThygeKristensen Contents 1Introduction 2PhasesofaProject 2.2RequirementsAnalysis ModellingandDesign ModelsoftheSoftwareDevelopmentProcess Implementation SystemTest ProjectManagement 3RolesinaProject 4.1ActivitiesandActivityScheduling RiskManagement SoftwareProjectDocumentation 4.3ProjectRecords Goalsfordocumentation Thestructureofthedocumentation Presentationrules Terminology Theuser'smanual Typography Languageandstyle Sourceprograms References

2 1INTRODUCTION 1 Introduction 2 ThesenotesgiveashortintroductiontoSoftwareEngineeringasitisusedinsoftware developmentprojectsofmoderatesize.softwareengineeringisthedisciplinewhichdeals notlivinguptheusers'expectations.thetechniquesdescribedinthesenoteshavebeen softwaresystemscommonlyhavehighinherentcomplexity,afactwhichoftenleadsto softwareproductshavingdefectivefunctionality,beingdeliveredlateorinotherways withthespecication,developmentandevolutionofsoftwaresystems.evenquitesimple developedovertheyearstohelpdeveloperscontrolthiscomplexityinamannerwhichleads tothedevelopmentofreliableproductswhichcorrectlyreectthecustomer'srequirements. Thenotesfallintotwomainparts.Intherstpart,weconsidertheactualprocessof sometechniquesusedformanagingprojects,inthesenseofplanningandmonitoringthe secondpart,weconsidersomeaspectsofsoftwareprojectswhicharemoreorientedtoward management:therolesplayedbythevariousparticipantsorstakeholdersinaproject,and carryingoutadevelopmentproject,itsphases,andtheresultsfromeachofthese.inthe useofresources. ThesenoteshavebeenwrittentohelpparticipantsintheInformaticsProjectscourse duringtheirsecondyearofstudyatdtu,butwehopetheywillbegenerallyusefulas thereareanumberofexcellentbooksonthistopic.weparticularlyrecommendthelatest ashortintroductiontothesubject.forthereaderinterestedinfurtherreadingmatter, (Sixth)editionofIanSommerville'sbook\SoftwareEngineering"[Som01]. 2Softwaredevelopmentisanengineeringprocess,andsoftwareprojects{likemostengi- neeringprojects{fallnaturallyintophases,eachofwhichfocussesonaparticularaspect PhasesofaProject ofthedevelopmentprocess.fourphasesareusuallyidentied: Requirementsanalysis:Theobjectivestobemetbythesoftwaresystem(togetherwith itshardwareplatform)aredenedincollaborationwiththeintendedusersofthe Modellinganddesign:Startingfromtherequirementsspecication,the\realworld" byallparticipants. system. conceptsemployedbytheusersareexpressedintermsofmathematicalmodelsor otherabstractdescriptions,andthecomponentsofthesoftwaresystemareidentied Theresultofthisphaseisarequirementsspecicationdocumentwhichisapproved andtheirfunctionalitiesspecied.

3 2PHASESOFAPROJECT 3 Implementation:Thecomponentsofthesoftwaresystemidentiedinthedesignspeci- uallytocheckthateachcomponentcorrectlyimplementsthefunctionalityrequired projectmanagement. cationareimplementedinanexecutableprogramminglanguageandtestedindivid- Theresultofthisphaseisadesignspecicationdocumentwhichisapprovedbythe ofit. Theresultofthisphaseisasetofcodemoduleswritteninthechosenprogramming Systemtest:Theindividualprogrammodulesareintegratedintoacompletesystem, workingofeachmodule. whichisthentestedtocheckthatoverallsoftwarerequirementshavebeenmet.this theresultsoftheindividualtests,andtechnicaldocumentationdescribingtheinternal issometimesknownasexternaltest,asthesystemistested\fromtheoutside", withoutregardforitsinternalstructure. language,atestschemeforeachmodule,statinghowithasbeentestedandgiving havebeencarriedoutandwhattheresultswere. industry,furtherphasesareadded,suchas: Moststudentprojectsmakedowiththefourphasesdescribedabove,butinprojectsin Weshalldescribethesephasesinmoredetaillaterinthesenotes. Theresultofthisphaseisatestschemefortheentiresystem,statingwhichtests Deployment:Thesystemissetinoperationontheuser'ssystemanditsacceptabilityfor Maintenance:Afterdelivery,manysystemsundergomaintenance,duetoaneedto: acceptancetest,wheretheusertakesoverthesystemasacorrectlydelivereditem{ andpaystheagreedsumtothesupplier. theintendedpurposeischecked.thisphasemayresultinaformal,legallybinding Correcterrorsinfunctionalitywhichdidnotbecomeapparentduringearlier Softwarecompaniesoftendiscoverthatmaintenanceisanexpensiveandtime-consuming Extendormodifyfunctionalityduetonewuserrequirements. Adaptthesoftwaretoanewhardwareorsoftwareenvironment. phases. Finally,itmustbenotedthatthephasesdescribedaboveonlyrefertosoftwaredevelopment.Inmanyprojects,theRequirementsAnalysisandDesignphasesincludeelementsof SystemsEngineering,inwhichdecisionsaremadeastowhichelementsofthetotalsystem areinfacttobeimplementedinsoftware.theremainderofthesystemthenconsistsof latertosomethingswhichcanbedonetoreducethisburden. phase,whichtakesresourcesawayfromimportantnewdevelopment.weshallreturn software,andassumethatthesystemsengineeringtaskhasbeencarriedout. hardware,existingcollectionsofdata(indatabasesorthelike),peopleperformingvarious functions(withorwithouttheuseofcomputers)andsoon.althoughinsometypesof systemthiscanbeveryimportant,weshallconcentrateinthesenotesonthedesignofthe

4 2PHASESOFAPROJECT 2.1 ModelsoftheSoftwareDevelopmentProcess 4 Thereareseveralacceptedparadigmsfortheprocessofsoftwaredevelopment,inwhich thephasesdescribedaboveareexploitedindierentways.theseareoftencalledmodels model,thephasesofrequirementsanalysis,modelling/design,implementationandtest aredealtwithasalinearsequenceofactivities,sothatworkonphasenstartswhenwork ofthesoftwarelife-cycle.inthesimplestmodel,knownasthewaterfallorlinearsequential onphase(n 1)hasbeensuccessfullycompleted.ThisisillustratedinFigure1. Systems Engineering Analyse Design Implement Test Delivery of product Thewaterfallmodelisaclassicalmodelofsoftwaredevelopmentderivedfrommodels usedinotherbranchesofengineering,andwasrstdescribedin1970byroyce[roy70]. Figure1:Thewaterfallmodelofsoftwaredevelopment Althoughitiswidelyused,ithasattractedagooddealofcriticism,asitdoesnot(at Time developmentprocess.aparticularproblemisthatitimpliesthatthespecication,once agreedon,isfrozen.ifanerrorisdiscoveredduringsystemtest,correctionsaretherefore madetotheimplementationratherthanthedesign.thismaybetheidealstateofaairs, leastinthesimpleformillustratedhere)describetheessentiallyiterativenatureofthe modelsthereforeoftenincorporateprocedureswhichallowformoreexperimentation. experiencetonalisethedesignbeforeattemptinganimplementation.modernlife-cycle butitisnotalwaysaverypracticalstrategytouseincomplexsystemsorinsystemswhich arebasedonquitenewprinciples,sincethedevelopmentteammaysimplynothaveenough onthefollowingpage.thisisanexampleofanevolutionarymodelwhichreectstheidea ThesimplestexampleofthistypeofmodelistheincrementalmodelillustratedinFigure2 thatasoftwareproductisproducedinanumberofversions,eachofwhichisastepwise improvementonthepreviousversion.forexample,itmaysolveamorecomplextask,

5 2PHASESOFAPROJECT 5 Systems Engineering Analyse Design Implement Test Delivery of 1st increment Increment 2 Analyse Design Implement Test Delivery of 2nd increment Delivery of Increment 3 Analyse Design Implement Test 3rd increment includemorecompletefacilitieswithinthegivenproblemdomain,oeramoreinteresting Figure2:Theincrementalmodelofsoftwaredevelopment... Analyse userinterfaceorwhatever.thedevelopmentofeachversionorincrementfollowstheusual sequenceofphases,witheachincrementstaggeredintimewithrespecttothepreviousone, Time sothatexperiencefrompreviousdesignscanbeincorporatedintothenewdesign.inthe gure,eachnewincrementstartssometimeduringthedetaileddesignphaseoftheprevious increment,butthedelaymayinsomecasesbemuchlarger,sothatdevelopmentofthe newincrementdoesnotstartuntilthepreviousincrementhasbeendelivered.insuch cases,thedevelopmentmodelbeginstoresembletheprototypingmodeltobedescribed next. iterativeformillustratedinfigure3.ineachiteration,thedevelopmentteamdiscuss theyareunabletoreachagreementonanalspecicationwithoutseeingthesystemin actionandevaluatingitsbehaviour.theentiredevelopmentprocessthentakesonthe Inaprototypingmodel,allthestakeholders(theusersandthedevelopers)recognisethat implementationandtest.theusersarethenaskedtoevaluatethesystemandtosuggest changes,whichresultsinarevisedsetofrequirements,whicharethenturnedintoadesign, implementedandtested.thiscyclicprocedurecontinuesuntiltheusersaresatisedwith withtheuserswhatthesystemistodo,andgothroughtheusualphasesofdesign, Prototypingreliesontheavailabilityofspecicationandimplementationtoolswhichpermitrapidimplementation,andthismodelistypicallyemployedinsoftwaredevelopment environmentswhereveryhighlevelprogramminglanguages{suchasfunctionallanguages andlogicprogramminglanguages{areused.thisreectsthefactthatsoftwaredevelop- thefunctionalityofthesystem. menttimeismoreorlesslinearinthenumberoflinesofcodetobewritten.soahigh-level

6 2PHASESOFAPROJECT 6 Design Implement Analyse Test Evaluate language,whichmakesitpossiblefortheprogrammertoexpressabstractideasveryconcisely,givesashorterdevelopmenttimethanalow-levelone.sincethemainideaisto Figure3:Theprototypingmodelofsoftwaredevelopment (Re-) Delivery of Test Implement final product agreeontheintendedfunctionalityofthesystem,eciencyisnotusuallyanimportant Thisisindicatedbythedashedboxesinthegure. subsequentlyviaa(re-)implementationinamoreecientprogramminglanguage,developmentofbetteralgorithms,ortheuseofhardwareplatformswithincreasedperformance. issuewhenprototypingisused.ifamoreecientversionisrequired,itwillbedeveloped Althoughprototypingsoundslikeanidealwaytoensurethattheusers'wishesaregenuinely reectedinthedesign,itinfactoftengivesrisetodisagreementsbetweenthedevelopment teamandtheusers.thisisbecausetheusersmaybelievethattheyhaveseenthereal productinoperationandarethusstronglydisappointedtohearthattheyhavetowait fordeliveryofaversionwhichcanbeusedinpractice.managersofteamswhichuse prototypingtechniquesneedtoexplainthiscarefullyatthestartoftheproject. 2.2 ThepurposeoftheRequirementsAnalysisphaseofsoftwaredevelopmentistoproducea cleardescriptionofwhattheusersrequirefromthenalsystem.theessentialquestionto beansweredatthisstageiswhatisthesystemtodo?itisimportantnottotrytothink abouthowthesystemistodothis;thisisamattertobeconsideredinthedesignphase. Veryoften,thecustomerinitiatestheprojectbyproducingaroughdescriptionofthe

7 2PHASESOFAPROJECT requiredproduct.thetaskofthedevelopmentteamistoaskrelevantquestionswhich7 enablethemtoturntheseroughideasintoamoredetailedandprecisedescriptionofwhat thesystemistodo.thisisnotaneasytask.almosteverybodyhasheardaboutcomputer systemswhichdonotfullthecustomer'srequirements.commonreasonsforthisare: EssentialquestionswerenotaskedduringtheRequirementsAnalysisphase. Therequirementswereformulatedintooimpreciseamanner. Thequestionswereputtothewrongpeople. Therequirementscontainedtoomanylow-leveldetails,makingitimpossibletoget thesystemissupposedtodo,withouttalkingtothestawhowillactuallyusethesystem. Awell-knownrecipefordisaster,forexample,istoaskthecustomer'stopmanagerswhat anoverallgraspoftheproblem. Requirementsareoftendividedintotwoclasses: reectthewayinwhichdataareactuallygatheredandusedinthecustomer'scompany. Notonlyisthispoorpersonnelpolicy,italsooftenresultsinasystemwhichdoesnot Functionalrequirements:Thesedescribethefunctionalityofthesystemandtheservicesitmustprovide,thesortofinputitmustdealwith,theformandappearance oftheoutputandsoon. Non-functionalrequirements:Thesedescribeconstraintsonthewayinwhichthesystemmustoperate,suchastimeandspacerequirements,easeofuse,securityrequirements,requirementswithrespecttohardwareorsoftwareplatform,standardstobe Thedivisionissomewhatarticial,sincerequirementswhichtotheuserappearnonfunctional(say,withrespecttosecurity)maytotheimplementorappearfunctional(the followedandsoon. thestyleoffeaturessuchashelpfunctionsanderrormessages.butthisclassicationisa systemmustoerfacilitiesforuserauthentication).likewise,easeofuseisregardedas usefulwayofstructuringthediscussionaboutwhatisrequired. anon-functionalrequirement,butstronglyinuencesthedesignoftheuserinterfaceand ThekeywordsforRequirementsAnalysisarecompletenessandprecision.Toensurecompleteness,youarerecommendedtomakeuseofachecklistoffunctionalandnon-functional requirementswhichneedtobegathered.forthefunctionalrequirements,youneedtomake surethatyouunderstand: Theconceptswhichareusedintheproblemwhichthesystemistosolve. Themodeofoperationofthesystem:interactive,batch-oriented,etc. Thesourceandformoftheinputdata:numerical,text,fromadatabase,fromale, Thefunctionstobeperformedbythesystemusingthesedata. viaanetwork,etc.

8 2PHASESOFAPROJECT Thedestinationandformoftheoutputdata,analogoustothedescriptionforinput 8 Thewayinwhichthesystemistoreacttoerrorsinthedata:(user-friendly)error data. Forthenon-functionalrequirements,alongerchecklistisrequired,forexamplebasedon exception,etc. messages,replacementoffaultydatabydefaultvalues,stoptheprogramwithan thetaxonomyshowninfigure4. Non-functional requirements Product Organisational External requirements requirements requirements Usability Efficiency Reliability Portability Interoperabilty Ethical Legislative requirements requirements requirements requirements requirements requirements requirements Delivery Implementation Standards requirements requirements requirements Themainclassesare: Figure4:Classicationofnon-functionalrequirements(after[Som01]) Performance Storage Privacy Safety requirements requirements requirements requirements Productrequirementsspecifyingthebehaviouroftheproduct,includingitsperformance,reliability,easeofuseandportabilitybetweenplatforms. Organisationalrequirementsderivedfrompoliciesandworkproceduresusedbythe Externalrequirementscoveringeverythingwhichisdictatedbyfactorsexternaltothe customerandthedevelopers,includingthelanguageofimplementation,platform (hardwareandoperatingsystem),standardsornormstobefollowed,deliveryschedulefortheproductanditsdocumentationandsoon. relatedtohowthesystemmayaectsystemsownedbythirdparties(interoperability stakeholders'organisations,suchaslegalandethicalrequirements,andrequirements Youshouldaimasfaraspossibletospecifyrequirementsintermsofquantitieswhichcan bemeasured,sothatitislaterpossibletoverifythattherequirementsaremet.table1 requirements). onthefollowingpageshowsometypicalmetricsusedforthispurpose. project,therequirementsareoftendescribedinnaturallanguage,sothatthecustomercan Alltherequirementsarecollectedupintherequirementsspecication.Atthisstageofthe

9 2PHASESOFAPROJECT ClassofrequirementTypicalmetrics 9 Speed Size Numberoftransactionspersecond Responsetimetouserinput Easeofuse Timetorefreshscreen Mbytesofstorerequired Reliability Gbytesofdiscspacerequired Daysoftrainingtime Numberofhelpframes Robustness Meantimetofailure(MTTF) Rateoffailureoccurrence Portability Availability Timetorestartafterfailure Percentageofeventscausingfailure Table1:Metricsfornon-functionalrequirements Numberoftargetplatforms mul,wheneverpossible.obviouslythisiseasierifthecustomersaretechnicallyminded! understandthem.however,naturallanguageisacommonsourceofmisunderstandings, andeveryeortshouldbemadetousemoreprecisenotations,suchasmathematicalfor- 2.3 IntheModellingandDesignphaseofasoftwaredevelopmentproject,afullspecicationis developedforthesoftwaresystem,sothatitcanbeimplementedasanexecutableprogram Modelling:Developmentofamathematicalmodelorotherabstractdescriptionofthe inthefollowingphase.asthenamesuggests,thisphasecanbedividedintotwoparts: Design:Identicationofasetofprogramcomponentswhichcanproducethefunctionality \realworld"problemidentiedintherequirementsanalysisphase. identiedintherequirementsanalysisphase,andspecicationoftheinterfaces ingtheightofarocket.theinitialfunctionalrequirementsarethattheprogramshould Asaverysimpleexample,letusconsideraprojecttodevelopasmallprogramforsimulat- whichtheyoertooneanother. provide:

10 2PHASESOFAPROJECT 1.Aninteractiveuserinterfaceforinput,atwhichtheusershouldbeabletoprovide 10 2.Agraphicaluserinterfaceforoutput,onwhichthepositionoftherocketrelative capacityofarocket. asetofdatadescribingtheinitialmass,thrust,fuelconsumptionandfuel 3.Thepossibilityofsimulatingseveralrocketightswithdierentsetsofinputdata passes,thepositionbeingevaluatedforevery100msofthesimulatedight. duringasinglerunoftheprogram. toitsstartingpointcanbeseeninatwo-dimensionalcoordinatesystemastime Asanon-functionalrequirement,thecustomerdemandsthatthepositionoftherocketin thegraphicaloutputshouldinfactbeupdatedonthescreenevery100ms,sotheuserof theprogramcanfollowasimulationoftherocket'sightinrealtime. A(somewhatsimplied)mathematicalmodelfordescribingthisproblemcouldbethe followingdierentialequationdescribingtheequationofmotionoftherocket: rocketand~vitsvelocity,allofwhicharefunctionsoftime,t.itisnotthepurposeofthese where~fisthethrustoftherocket,~gtheaccelerationduetogravity,misthemassofthe ~F+~gm=ddt(m~v) deriveanexpressionforthepositionoftherocket,~x,asafunctionoft. notestodiscusshowtosolvethisequationindetail,butifyouhavejustanelementary knowledgeofthedierentialcalculusyouwillrealisethatthisequationcanbeusedto Justintroducingthismodelalsointroducesanotationforseveraloftheconceptsmentioned decidehowtheseconceptsaretobeexpressedintermsofquantitieswhichmightappear innaturallanguageinthefunctionalrequirementsspecication.thenextstepisthento inaprogramminglanguage,sothattheycanbereferredtointhedescriptionsofthe interfacestothevariousmoduleswhichmakeupthesystem.firstly,weneedtodenethe typesusedtorepresentthesequantitiesintheprogram,forexample: vx,vzreal Fx,Fzreal tname integertimeinunitsof100ms. Type Componentsofvelocityvectorattimet(m/s) Componentsofthrustvectorattimet(Newtons) Description mr0m mf0 x,z Initialmassofrocketwithoutfuel(kg) Massofrocket+fuelattimet(kg) Fuelcapacity=initialmassoffuel(kg) Componentsofpositionvectorattimet(m) andsoon.thenexttaskistodesignsomemoduleswhichperformessential,well-dened functionsinthecontextoftheproblem.forexample,wemightidentifyfunctionswiththe fuelc real Fuelconsumptionofrocket(kg/s) followingtypes:

11 2PHASESOFAPROJECT typethrustvec 11 typevelocityvec=(real*real) typepositionvec=(real*real) typemass typeconsumption=real typetime simstep: input_rocket:unit->mass*thrustvec*consumption*mass positionveclist*velocityvec*thrustvec*mass*time-> =int output_orbit:time*positionveclist->unit Thesetypesandsignatureshavebeengiveninafunctionalprogramminglanguage,inthis casesml.westronglyrecommendyoutofollowthispractice,sothatthelogicaldesign input_rocket()inputsanewsetofdataforasimulation.theuserispromptedfora thedetailsofimplementation.thepurposeofthesefunctionsisasfollows: oftheprogramcanbecompletedatahighlevelofabstractionbeforeattentionispaidto theinitialmassoffuel,asprovidedbytheuser. newsetofdata,andthefunctionreturnstheinitialmassoftherocketwithfuel,apairof simstep(pvl,v,f,m,t)takesalistofpositionvectors,pvl,whoseheadisthelatest realvaluesgivingthexandzcomponentsoftheinitialthrust,thefuelconsumptionand thesequantitiesattheendofthenextsimulationintervalof100ms.thenewvaluesare (current)positionvector,togetherwiththecurrentvelocityvector,v,thecurrentthrust vector,f,thecurrentmass,m,andthecurrenttime,t,andreturnsthevaluesofall assumedtobeevaluatedbymakinguseofthedierentialequation.thenewposition vectorisappendedattheheadofthepositionvectorlist. rocketuptothegiventime,asdescribedbythesequenceofpositionsinthelist. isthelatestpositionvector,andupdatesthegraphicalinterfacetoshowthepathofthe output_orbit(t,pvl)takesatime,t,andalistofpositionvectors,pvl,whosehead asimulationisperformedcorrespondingtoanumberofsimulationintervalsof100ms, Thesefunctionsneedtobecontrolledbyamainprogramwhichcandealwithoneormore ightsimulations.ineachsimulation,asetofinputdataisobtainedfromtheuser,and startingfromtheinitialpositionx=z=0withvelocity0,andcontinuinguntileitherthe tobeusedbytheuserforthispurposeneedstobespecied.weshallnotgointofurther detailshere. rocketlands(zbecomes0again)orthesimulationisabortedbytheuser.themechanism Thedesignsoftheuserinterfacesforinputandoutputarealsocompletedatthisstage,and thedevelopmentteammightdecidethattheoutputfortherocketsimulationprogram includedinadesignspecicationsothatthecustomerscanapprovethem.forexample,

12 2PHASESOFAPROJECT 12 Position z (km) Time= s shouldlookasshowninfigure5.thisgureshouldbesupplementedwithannotations Figure5:Exampleofgraphicalinterfacedeterminedduringdesignphase whichexplainwhatthesignicanceofthetextandnumericaleldsinthediagramis,and wheretherelevantdatacomefromintheprogram{i.e.whichvariablestheygivethe Position x (km) valuesof,orhowtheyarecalculated.forexample,thevaluegivenforthetimeatthe topleftcornerofthegureisthevalueofthecurrenttimeinseconds,evaluatedfromthe internalquantitygivingthetimeinunitsof100ms.similarly,thesizeoftheoutputin Someofthesedecisionsmaymeanthatthedevelopmentteamneedtoaskthecustomerfor relationtothepageorscreenmustbespecied{foragraph,forexample,rulesforscaling theaxestosuitthesizeofthecurvemustbegiven. moredetailsaboutwhatisrequired.thisisquiteacceptable.whatcannotbeacceptedis ifthedevelopmentteamomittoaskthecustomeraboutmatterswhichtheyareindoubt about,andjustmakesomekindofarbitrarydecision{\theyprobablywanteditlikethis" or\we'lljustdoasweusuallydo". Exercise:Severalofthedesigndecisionsdescribedintheprevioussectionwerenot actuallyspeciedintheoriginalfunctionalspecication,asgivenonpage10.listthese decisions.suggestfurtherquestionswhichitwouldhavebeennecessarytoputtothe 2.4 customerinordertocompletethefunctionalandnon-functionalrequirements. IntheImplementationphaseoftheproject,thesoftwarecomponentsspeciedduringthe ModellingandDesignphaseareimplementedinsomesuitableprogramminglanguage. Implementation Thelanguagemayalreadyhavebeengivenasanon-functionalrequirementduringthe

13 2PHASESOFAPROJECT RequirementsAnalysisphaseorbeselectedatthestartoftheDesignphase.Ifnot,itis 13 decribesthesoftwarecomponents,theirinterfacesandthewayinwhichtheyinteractwith chosennow. SinceweassumethattheModellingandDesignphaseendsupwithaspecicationwhich oneanother,itshouldbeclearthattheimplementationphasejustinvolvesdeveloping correctcodeforeachcomponent,inordertoachievethedesiredfunctionality.toputit anotherway:thedesignphaseendswithdescriptionsofthecomponentsviewedasblack boxes,whileintheimplementationphasetheinternalmechanismsoftheseblackboxesare determined. equation.thedetailsofthiswilldependonhowaccuratetheresultisrequiredtobe{yet Thisisclearlyseenintherocketexample,wherethefunctionsimstepevaluatestheposition,velocity,thrustandmassattheendofthenextintervalof100msofsimulatedight anotherexampleofanon-functionalrequirementwhichthedevelopmentteamwillhaveto time.todothis,itisnecessarytodevelopasuitablealgorithmbasedonthedierential askthecustomerabout. theinformationcorrespondingtothemovementwhichhastakenplaceinthemostrecent orwhetherthepreviouspositionswillberemembered,sothatitisonlynecessarytoadd Similarly,intheimplementationofoutput_orbititisnecessarytodecidewhetherthe intervalof100ms.thisagainwilldependonthenatureofthefacilitiesavailablefor entirelistofpositionvectorsistobeplottedonthegrapheachtimethefunctioniscalled, themtodesignadditionalmodulesforthispurpose. thedevelopmentteamwillevenhavetodevelopthesefacilitiesthemselves,whichmaylead plottinggraphsintheprogrammingenvironmentchosenfortheimplementation.maybe Foraninexperiencedprogrammer,thisphaseisthebiggestchallenge.Fortheexperienced softwareengineer,ontheotherhand,itisusuallythephasewhichrequiresleasteort, sincetheexternalconditionsforallofthemodulesaregiven. Ausefulprincipletofollowduringimplementationisthatoftraceabilityofconcepts.In orlessformal)designspecicationshouldalsoberecognisablypresentinthecode.itis otherwords,conceptswhichappearedintheinitialrequirementsandlateroninthe(more andconfusingintherocketightsimulatorsuddenlytoletthetimebegivenbyaquantity notagoodideatointroducecompletelynewnotationorideasatthisstageortochange thingsradicallyinrelationtowhatwasplanned.forexample,itwouldbeinappropriate notjustbeallowedtodisappearinthenalimplementation. AnimportantaspectoftheImplementationphaseistestingofthemodulesastheyare oftypereal.similarly,conceptswhichhavebeenreferredtointhespecicationshould unitbasedonknowledgeofhowitworksinternally.atypicalaimistocheckthatallpaths developed.thisisaso-calledinternaltest,inwhichthedeveloperstestouttheprogram throughthemodulehavebeenactivatedandworkinaccordancewiththeirspecications.

14 2PHASESOFAPROJECT Thisisoftenknownasapathtest.Eachtestcaseinapathtestusesasetoftestdata 14 whichwillcauseexecutionoftheprogramunittofollowaparticularpaththroughthe whichforeachtestcasespecies: Thepurposeofthetestcase,i.e.whatthetestisintendedtodemonstrate,whichin pathtestingwilldescribethepathtobefollowed. code.thetestsperformedforeachmodulearedocumentedintheformofatestscheme, Theexpectedresultfromthetest. Toperformsuchasetoftestsonaprogrammodule,themodulemustbeinsertedina Thetestdataactuallyused. smalltestprogramwhicheitherobtainsinputfromthepersonrunningthetestorfroma Theresultobserved,andwhetherthisisinaccordancewithwhatwasexpected. withtheprogrammoduleinthedocumentationdeliveredattheendoftheimplementation leoftestdata,orwhichgeneratestestdataautomatically.thetestschemeisincluded phase. 2.5 ThenalphaseinanydevelopmentprojectistheSystemTestphase,whoseaimisto checkthatthecompletesystemoperatesinaccordancewiththeagreedspecications.the functionscorrectly,andthatitalsofullsitsnon-functionalrequirements,totheextent thatthesecaninfactbetested{thisisobviouslydicultforethicalrequirements,for systemisassembledfromitscomponents,andistestedasawhole,withoutregardforits example! internalstructure.theaimistocheckthatthesystemcanperformallofitsintended AsinthecaseoftheinternaltestsofindividualmodulesperformedduringtheImplementationphase,thedevelopmentteammustworkoutatestscheme,whichforeachtestcase species: Theexpectedresultfromthetest. Thepurposeofthetestcase,i.e.whatthetestisintendedtodemonstrate. Thepointofhavingsuchatestschemeisthatitmakesitpossible,ifthesystemismodied Thetestdataactuallyused. orerrorsaredetectedatalaterstage,toseewhichtestswereoriginallyperformedonthe Theresultobserved,andwhetherthisisinaccordancewithwhatwasexpected. Inprinciplethetestschemeshouldincludesucienttestcasestoexercisetheentirefunctionalityofthesystem.Inpracticethisisofteninfeasibleduetothesystem'scomplexity, systemandtorepeatthemifnecessary.

15 3ROLESINAPROJECT andchoiceshavetobemade.ifthisisthecase,youshouldrememberthatitismore 15 importanttotestthefunctionswhicharecommonlyusedthanthosewhichareonlyused rarely. 3Exceptincaseswhereasinglepersonperformsaprojectforhisorherownenjoyment, RolesinaProject ndhim/herselftakingonseveralroles,whileinlargeteamsseveralpeoplemayplaythe organisationorexecutionoftheproject.inprojectswithfewparticipants,onepersonmay correspondstoa\logicalperson",whoperformssomekindoffunctionrelatedtothe projectsinvolveanumberofdierentpeople,whotakeoncharacteristicroles.arole samerole. Thecustomer:Thecustomeristhepersonororganisationwhoshouldbenetfromthe Wecancharacterisethetypicalrolesinasoftwaredevelopmentprojectasfollows: resultofthesoftwareproject.customersare(normally)characterisedbyspeakinga non-technicallanguage,usingconceptswhicharecharacteristicfortheproblemarea inwhichtheywork.often,thecustomerhasverydiusewishes,andexpressesbasic Theexecutive:Thisisthepersoninthesoftwaredevelopmentorganisationwhocontrols materialwhichheorsheprovides.inthenalanalysis,thecustomerdenesthe andimportantdemandsinanimplicitmanner\betweenthelines"ofthewritten wantstobeinformedaboutthestatusoftheproject,itshistory,andtheplansfor thesettingoftheproject,andcanadjusttheavailableresources.theexecutiveoften overallresourceswhichcanbeexpendedontheproject. Thedesigner:Thedesignerisresponsibleforunderstandingthecustomer'sdemands howitisexpectedtodevelop.theexecutiveismainlyinterestedinexpressingthings withrespecttotheresultoftheproject.aftergainingthatunderstanding,the intermsofcostsandearnings,whereastheinternaldetailsoftheprojectareoflittle designermusttransformthedemandsintoaconceptualframedescribingthefunctionalityinanimplementableway.thusthedesignermustbeabletohandleboth theconceptsusedbythecustomerandthetechnicalconceptsusedinsoftwaredevelopment.thismeansthattheroleofthedesignerneedstobelledbyavery interest. Theprogrammer:Theprogrammerhastounderstandthedesigner'sdescriptionofthe experiencedpersonwhoisbothcreativeandsystematic. Essentially,thedesignerbuildsthebridgefromtherequirementsspecicationtothe designspecication. intendedresultoftheprojectandtotransformthatdescriptionintosourcecodethat realisestheproduct.

16 3ROLESINAPROJECT Itisalsotheprogrammer'sresponsibilitytoverifythatthefunctionalityofthesource 16 codewhichheorshewritesisthesameasthatdescribedbythedesigner.this wholesystem.thisrolealsodemandsacertaintalentforself-discipline,sothatthe programmer'screativitystayswithinthelimitssetbythedesigner.otherwisethe vericationisdonebyappropriatetesting,asdescribedabove. workoftheprogrammercouldchangetheprojectresultinanunwanteddirection. Itisanadvantagetotheprogrammertohaveinsightintotheinternalstructureofthe Thebookkeeper:Thebookkeeperkeepstrackofallthematerialcreatedduringthe Theprogrammermustdoapuretransformationoftheproductdescribedbythe dierentphasesoftheproject,registerstheresourcesused,andkeepstrackofthe degreeofcompletionoftheproject. designerintoaworkingpieceofsoftware. Thecomptroller:Thisisthepersonwhoensuresthattheresultoftheprojectiswhatthe Thebookkeeperalsohastostoretheitemsproducedinallphasesoftheprojectin suchawaythattheycanalwaysberetrieved,andsothatallparticipantscanalways ndinformationaboutthecurrentstatusofthevariousparts. whicharecarriedoutduringthephasesoftheproject.hemustensurethatfunctions requiredbythecustomerdonotjust\disappear"andthatunwantedfunctionsare oftheproductiskeptinvariantthroughoutthevarioustransformationprocesses customerhasordered.sothejobofthecomptrolleristoensurethatthefunctionality involvedkeepupagoodteamspirit. oftactanddiplomacy,sothedevelopmentprocessstaysontrackandthepeople Thecomptrollerhastocombineagoodoverallgraspofthesystemwithagoodsense notintroduced. Theprojectleader:Theprojectleadermustensurethateveryoneperformsinaccordancewiththeirroles,anddistributesthetaskstothecast.Theleadermustsupervisethatthetasksarecarriedoutwithinthelimitstoresourcesgivenbythe executive,andifnecessarytransferresourcesbetweentasks. Thisroledemandsagoodknowledgeofhumannature,inordertokeepapleasant Instudentprojects,wherethedevelopmentteamtypicallyconsistsofoneortwostudents, atmosphereamongtheparticipantsinvolvedintheproject,whomtheprojectleader thecustomeristhepersonwhoposestheproblem,whileseveraloftheotherrolesmaywell mustprotectfromdirectcritisismfromtheouterworld. decisionabouttherunningoftheproject,whilethenextdayheorshereturnstobeing sothatdecisionscanbemadeinarealisticmanner.forexample,oneofthedevelopment teammayputtheprojectleaderhatonfromtimetotime,inordertomakeastrategic beplayedbythesameperson.nevertheless,itisimportanttobeawareofalltheseroles, anordinaryprogrammer,inordertogetonwiththeimplementation.togetabetteridea aboutprojectmanagement,youshouldtrytomakesurethatyourealisewhichroleyou topicinthenextsectionofthesenotes. areplayingwhenevertheprojectteammeettodiscusstheproject.wewillreturntothis

17 4PROJECTMANAGEMENT 4 ProjectManagement 17 Projectmanagementincludesallaspectsofgettingaprojecttorunontimeandwithin theagreedbudget.inthisrespectsoftwareprojectsarenodierenttoprojectswithin otherengineeringdisciplines.ontheotherhand,softwareprojectsarecharacterisedby on,andincreasestheneedforappropriatewrittenmaterialwhichdocumentsprogress. theproductbeingintangible:youcannotseeitdevelopinglikeabridge,anairplaneoreven anitemofcomputerhardware.thismakesitmorediculttokeeptrackofwhatisgoing followingissues: Personnel:Theallocationofpersonneltothedevelopmentteamandtheroleswhich Forprojectsinvolvingcomputersystems,projectmanagementdealsparticularlywiththe Resourcerequirements:Thehardwareandsoftwareneededforexecutionoftheproject individualpeoplearetoplayarespecied. Activityscheduling:Thetimerequiredtocompleteeachactivity,theallocationofpersonneltoactivitiesandthedependenciesbetweenactivitiesaredescribed,anda Workbreakdown:Theprojectisbrokendownintoactivities,andthedeliverablesand milestonesforeachactivityarespecied. isspecied,andpricesanddeliveryschedulesaredetermined. Riskmanagement:Projectrisksareidentied,thelikelihoodoftheserisksarisingis estimatedandcontingencyplansaresetupfordealingwiththerisksiftheyarise. Thismayresultinoneormorealternativeprojectschedulesbeingdeveloped. completescheduleforallactivitiesisworkedout. Intheinitialstagesoftheproject,aplandealingwithallthesepointsisdrawnup.As (whoarebynomeansnecessarilythesameasthedevelopmentteam)aboutprogress.the theprojectprogresses,thedevelopmentteamneedtoreporttothemanagementteam managementteammustlaydownrequirementsforhowthisreportingistotakeplace. WehavealreadydiscussedthequestionofrolesinSection3onpage15.Thedetermination ofresourcerequirementsisarelativelysimplematterandwillnotbediscussedfurtherhere. Thefollowingsectionswilldiscusstheremainingissuesinmoredetail. tomanagetheprojecteectively.withineachactivityitisnecessarytohaveatleast 4.1 Divisionofaprojectintowell-denedactivitiesisanessentialpre-requisiteforbeingable ActivitiesandActivityScheduling onemilestone,whichmarkstheendoftheactivity.eachmilestonemustbecharacterised byaverbalpresentation,apieceofdocumentationorsomeothertangibleitemwhichis tobedeliveredbythedevelopmentteam.arealisticperiodoftimeshouldbesetaside

18 4PROJECTMANAGEMENT forreachingthismilestonefromthestartoftheactivity,andthepersonnelneededfor 18 performingtheactivitymustbeidentied. wherethemanagementteamevaluatetheprogresswhichhasbeenmadeintheproject Amilestoneisaninternalprojectevent,andthematerialwhichisdeliveredisintendedfor themanagementteam.itisoftenagoodideatoassociateeachmilestonewithareview, andcheckthequalityofwhathasbeenproduced.manymethodshavebeenproposedfor checkingsoftwarequality;asimplebuteectivemethodwhichwerecommendtoyouisthe walkthrough.hereoneormorepersons,whohavenotbeendirectlyinvolvedinaparticular peoplewhohaveproducedit.theeectofhavingtoexplainwhatthedocumentation activity,gothroughthedocumentationorprogramproducedduringthatactivitywiththe Somemilestonesmayfurtherbecharacterisedbyadeliverable,whichisanagreeditemtobe meansorhowapartoftheprogramworksisinmanycasestoreveallackofclarityoreven genuineerrors,whichcanthenbeeliminated. projectandthemodelofthesoftwarelife-cyclewhichisbeingused.ifthewaterfallmodel isused,forexample,theminimumsetofdeliverableswouldincludetheuserrequirements deliveredtothecustomer.deliverablesmaybeitemsofdocumentationoractualsoftware modules.thenumberandscheduleofdeliverablesdependsstronglyonthesizeofthe schemesforinternaltestandsystemtestwouldalsobedelivered. Onceactivitieshavebeenidentiedandpersonnelallocated,itbecomespossibletodetermineanactualschedulefortheentiresetofactivitiesinvolvedintheproject.Therearea specication,theactualsoftwareproductandtheuserdocumentation.ifthecustomer numberoftechniques(andassociatedcomputer-basedtools)forndingfeasibleschedules{ requestedfullinsightintothedesign,theinternalprogramdocumentationandthetest Inthegure,activitiesaredenotedbyrectangularboxes,andmilestonesbyovalboxes. andsuchthatthesamepersonnelorotherresourcesarenotallocatedtotwoactivitiesat thesametime.anexampleistheactivitygraphshowninfigure6onthefollowingpage. i.e.schedulessuchthattheactivitiesareperformedwithduerespectfortheirdependencies, Dependenciesaremarkedbyarrows:anarrowfromAtoBmeansthatBdependsonthe completionofa.theheavypaththroughthegraphisthecriticalpath,whoseduration givestheminimumtimerequiredtonishtheproject:55days,inthiscase.delayson Eachactivityinthegraphismarkedwiththeestimatedtimerequiredforitsperformance. anyotherpaththroughthedirectedgraphdonotnecessarilydelaythecompletionofthe project.toolsforhandlingactivitygraphscanoftenautomaticallyworkouthowmuch tobemissed.analternativetechniquetotheactivitygraphistheactivitybarchart (organttchart),whereeachactivityismarkedonacalendarasabarwhichreectsits agivenmilestoneoractivitycanbedelayedwithoutcausingtheoverallprojectdeadline estimatedandmaximumpermissibleduration.

19 4PROJECTMANAGEMENT days M1 A2 15 days 8 days A9 A1 5 days M3 A5 M6 M7 start 15 days A3 20 days A6 A11 7 days 10 days 10 days A4 M4 A7 M5 15 days M8 A10 10 days M2 A RiskManagement Figure6:Activitygraphforaproject 25 days A8 finish Riskanalysis:Potentialrisksandtheirconsequencesarelisted,andthelikelihoodof Riskmanagementistheactivityofevaluatingrisksandcontingencyplansfordealingwith themiftheyshouldarise.thisisoftendividedintothreeparts: Riskplanning:Planstoavoidtheriskortominimiseitseectsontheprojectaredrawn Riskmonitoring:Eachriskisassessedatregularintervals,anditslikelihoodandeect eachofthemoccurringisdetermined. up. Typicalrisksinindustrialprojectsinclude: arere-evaluated. Changeofmanagement, Failureofasuppliertodeliverhardware(ornecessarysoftware), Staturnoverinthedevelopmentteam, Changesincustomerrequirements, Imprecisespecication, Faultyestimationofcostorsizeofsystemcomponents, Usually,theprobabilityofariskarisingisestimatedinaveryroughmanner(high,medium, Technologychangeswhichmakethetechnologyoutmoded, low)anditseectsinasimilarmannerasbeingcatastrophic,serious,tolerable(marginal) Competitionfromothercompanies.

20 4PROJECTMANAGEMENT ornegligible.obviously,allcatastrophicrisksandmostseriousrisksneedtobetaken 20 seriouslyandacontingencyplanneedstobedrawnuptodealwiththosewhoseprobability ofoccurrenceisnon-negligible. estimatesoftheirlikelihoodofoccurringandtheconsequencesiftheyoccur. Exercise:Investigatetheriskswhicharelikelytooccurinastudentproject,giving Activityschedulingreliesongoodestimatesofthedurationoftheindividualactivities. 4.3 Althoughsomegeneralresultsareknownforalltypesofproject,forexamplethatAnalysis ProjectRecords developmenttimeisrelatedtothenumberoflinesofcode(seetable3),moredetailed estimatesforparticularsoftwareengineeringmethodsandtypesofsoftwarearebasedon experience.systemtype anddesigntakeabout40%oftheresources(seeforexampletable2),androughlyhow Commandandcontrol Spaceborne Analysis/DesignImplementationTest 46 Phasecosts(%) Operatingsystem Scientic Business Table2:Relativecostsofsoftwaredevelopmentactivities(after[Boe95]) 28 Algorithmicallyheavyprogram Simpleapplication Auxiliary/serviceprogram TypeofSoftware Manpowerrequired(man-months) 2:4kLOC1:05 Systemprogram 2:8kLOC1:10 3:2kLOC1:15 Table3:Developmentcostsrelatedtoprogramsize 3:6kLOC1:20 Here1kLOC=1000linesofsourcetext,and1man-monthis1.4 calendarmonths. Thevaluesinthetableareforaverageprogrammers.Forinexperiencedprogrammers,multiplybyatleast4;forexperts,multiply by0.3(iflessthan300loc)to0.5(morethan1kloc).

21 5SOFTWAREPROJECTDOCUMENTATION Toaccumulatethisexperience,youshouldalwayskeeptrackofhowmuchtimeyouused 21 Youcanusefullycombinethiswithalistofmeetingsheldanddecisionsmadeduringthe toperformthevariousactivitiesinaproject.werecommendyoutokeepadetailedrecord project,sothatittakestheformofaprojectdiary.forexample,everytimeyouhavea project-relatedmeetingofanykind(eitherinternallyinthedevelopmentteamorwiththe themilestonesreached,deliverablescompletedanddocumentsproduced)astimegoesby. ofthisinaprojectnotebook,inwhichyourecordtheprogressoftheproject(especially customer,externalconsultantorwhatever),younotedown: Whatthepurposeofthemeetingwas Whenandwherethemeetingtookplace Whowaspresent importantones,atwhatstagethingswentwrong(iftheydid),andwhatitcosttocorrect Whentheprojectisover,youcanlearnalotbylookingbacktoseewhichdecisionswere Whatdecisionsweremade dierenttypesoffault. 5Softwareneedstobecarefullydocumentedifitistobeuseful{almosteverybodyhas SoftwareProjectDocumentation producttondouthowtouseitorhowitworksinternally.goodqualitydocumentation above,isthatsoftwareisintangible,soitisnotingeneralpossiblejustbylookingatthe experienceofpoorlydocumentedsoftwareproducts,andknowshowtime-consumingand needstobeproducedaspartofeveryserioussoftwareproject. frustratingtheyaretodealwith.oneofthemainreasonsforthis,aswehaveremarked Userdocumentation:Thisisintendedtotelltheuserofthesoftwareaboutwhatthe Documentationfallsintothreegeneralcategories: Programdocumentation:Thisisintendedtotellprogrammershowtheprogramworks Projectdocumentation:Thisisintendedforthecustomerwhoinitiatedthesoftware softwareproductcando,andhowtoinstallandrunit. internally,andhowithasbeentested. Intheprevioussectionsofthesenotes,wehavemarkedimportantcomponentsofthis projectandforthemanagersoftheproject,tospecifytherequirementsandtokeep documentationwiththesign inthemargin.tosummarisethese: trackofprogressanduseofresourcesinallphasesoftheproject. Therequirementsspecication

22 5SOFTWAREPROJECTDOCUMENTATION Thedesignspecication 22 Theinternaltechnicaldocumentationoftheindividualmodulesofthesoftware. Thetestschemesfortheindividualmodulesfromtheinternaltestperformedduring Theprojectnotebookcontainingprojectmanagementinformation,suchasminutes Thetestschemesforthecompleteproductfromthesystemtestperformedduring thesystemtestphase. theimplementationphase. Inthissectionweshalllookinmoredetailatwhatthedocumentationshouldcontainand fromallprojectmeetings,managementdecisions,informationaboutmilestonesand howitshouldbeorganised.muchofthesectionisbasedonthegeneralideaspresentedin deliverablesanddocumentationfortheuseofresourcessuchastimeandmoney. 5.1 reference[ris00]. Thegoalofanydocumentationcanbesummarisedintwopoints: Goalsfordocumentation Thedocumentationshouldbeusefultothereader.I.e.whenconsultingthedocumentationthereadershould {getalltheinformationwhichisneeded Notethatthesegoalsconictwithoneanother.Forexample,repeatingthesameinformationatseveralplacesinthedocumentationmaybehelpfulforthereader{butit documentationwillhavetondacompromisebetweenthesetwogoals. Youmustalsorememberthatthedierenttargetgroups{usersofthesoftware,program- isanuisancewhenthedocumentationistobeupdated.thusthepersonwritingthe Thedocumentationshouldbeeasytoupdatetoanewversionoftheproduct. {notgetinformationwhichisnotneeded theyhavedierentwaysofthinkingabouttheproduct.indeed,theyoftendiermarkedly mers,managersetc.{havedierentrequirementswithrespecttothedocumentation,as intheirgeneralknowledgeofsoftware.forexamplethesecretarywhousesanocesystem ideaofwhatacomputerprogramisorwhatgoesoninsidethecomputer;hopefullythisis notthecasefortheprogrammersortheirmanagers!whenproducingdocumentationyou andthedoctorwhousesacomputerisedpatientdatasystemmayonlyhaveaveryvague oneachlevelyoumustbeabletowriteonthepremisesofaparticularkindofreader. mustthereforebeabletomakedescriptionsofthesameproductondierentlevels,and

23 5SOFTWAREPROJECTDOCUMENTATION 5.2 Thestructureofthedocumentation 23 shouldfollowthegenerallyacceptedstyleofscienticreports,withsectionsasfollows: astudentproject,asinglereportwillnormallybesucient.thestructureofsuchareport intheformofseparatereportsintendedforthevarioustargetgroupsmentionedabove.in Inalarge,industrial-scaleproject,theitemsofdocumentationwilltypicallybeproduced 2.Theproblemtobesolved.Thisshouldgivethereaderageneralintroductiontothe 1.Abstract/introduction.Thisgivesashortsummaryofthecontentsofthereportand itsstructure. problemdomainanddescribetheactualproblemtobesolved.keyconceptswhich descriptionoftheunderlyingtheoryisgiven.ifamoreextensivepresentationofthe willbeusedintheremainderofthereportareintroducedanddened.aconcise 3.Therequirementsspecication. 4.Thedesignspecication. theoryisrequired(forexamplewithlong,detailedproofsofparticularresults),it 5.Ageneraloverviewpresentingthedetaileddesignofthesoftwareasimplemented. shouldappearinanappendix. 6.Thetestschemesforthesystemtestofthecompletesoftwareproduct. Thisshoulddescribetherelationshipsbetweentheindividualmodules,suchasthe 7.Aconclusiondescribingthestateoftheproductasdelivered,includinganyknown wayinwhichtheydependononeanother,andtheinternalworkingofthesemodules. faultsormissingfeatures(inrelationtotherequirementslistedintherequirements Notethatdetailedprogramlistingsshouldbepresentedlaterinanappendix. Moredetailedmaterialwhichisonlyofinteresttoparticulargroupsofreadersisusually 8.Alistofreferencesforliteraturereferredtointhereport(seeSection5.6below). specication),andsuggestionsforimprovements. placedinappendices,forexample: D.Thetestschemesfromtheinternaltestoftheindividualsub-programsintheindividualmodules(fortheprogrammers). A.Theuser'smanual(fortheusers).WereturntothisinSection5.4below. C.Theactualsourcetextofthesoftware(fortheprogrammers);seeSection5.5below. B.Theprojectnotebook(forthemanagers). E.(optional)Detailedtheoreticalresults,proofsorderivations. itisimportanttofollowsomegeneralrulesforpresentingthedocumentationinamanner 5.3 Inadditiontofollowingamoreorlessstandardisedwayoforganisingthedocumentation, Presentationrules whichmakesitaccessibletothereader.

24 5SOFTWAREPROJECTDOCUMENTATION 5.3.1Terminology 24 Theterminologyisthesetoftermsusedtodenoteconceptspertainingtothesoftware symbolsusedinguresarealsopartoftheterminology. Aswehavealreadymentionedduringourdiscussionofthedesignprocess,asoftware producttogetherwiththeirprecisemeaningwhenusedinthedocumentation.graphical productshouldwheneverpossiblebedescribedintermsofacceptedconcepts,termsand theproblemdomainhavetobeusedinveryprecisemanner{typicallymoreprecisethan understandingthedocumentation,andmaywellgiveup.ontheotherhand,termsfrom newtermsforwell-knownideas,asthereaderthenhastoputmuchmoreeortinto symbolsfromtheproblemdomain.ingeneral,itisapoorideatoinventcompletely isusualwhenpeoplediscussthingsinformally.thismaymakeitnecessarytoexpressner betweentermswhich(inothercontexts)areoftenconsideredsynonymous. Thebasicrulesforterminologyindocumentationare: distinctionswithmoreconcepts,soonewillhavetoinventnewterms{ortodierentiate Consistency:Alwaysusethesameterm(orsymbol)todenotethesameconcept. Dierentiation:Usedierentterms(orsymbols)todenotedierentconcepts. Notethattheserulesareinconictwithastylisticrulerequestingtheuseofavaried languagetocreateauenttext.thisstylisticruledoesnotapplytotheterminologyof softwaredocumentation,whereconsistentuseoftermsandsymbolsismuchmoreimportantthanlinguisticvariation. Thefollowingstylisticrulesshouldbeusedwhenwritingdocumentation: 5.3.2Languageandstyle Useshortsentences{avoidlongconvolutedsentences. Avoidchattering\small-talk"{andremovesentenceswhicharenotessentialfor Useexamplesinsteadofverboseexplanationsintutorialmaterial. Usegureswhenappropriate. Theuseofguresmustbeconsistentwiththewrittentext. conveyingthemessageofthesectionbeingwritten. Usetablesinthetexttoarrangereferentialmaterialinasystematicway. Giveguresandtablestitles(\captions")whichsummarisetheinformationsupplied. Ifnecessary,supplementthecaptionwithanexplanationofanyspecialsymbolsor othernotationusedinthegure.

25 5SOFTWAREPROJECTDOCUMENTATION Literaryskillsareratherusefulwhendocumentingsoftware,butdon'tgetcarriedaway. 25 Useshortandconciselanguage{youarenotwritinganovel. Makesuretodividethechaptersorlargesectionsofthereportintosub-sectionsina ideaofthesection'scontents.eachsectionshouldstartbytellingthereaderwhatthe naturalway.eachsectionorsub-sectionmusthaveatitlewhichgivesthereadersome beusefultotellthereaderwhatheorsheisexpectedtogetoutofreadingthesection sectionisabout,eitherdirectly(\inthissectionwedescribethestylisticrules...")ormore indirectly(\thefollowingstylisticrulesshouldbeused...").insomecontexts,itcanalso concerned,andtonishthesectionwithalittlesummaryofwhathasbeenpresented. Youshouldalwaystrytokeepthelevelofdetailconstantthroughoutasectionorsubsection;ifyouneedtopresentaparticularsubjectinmoredetail,thenstartasub-(or sub-sub-)section.forexample,thepartofthesenoteswhichyouarereadingatpresent isasub-sub-sectiongivingdetailedrulesforlanguageandstylewithinasub-sectionon 5.3.3Typography PresentationRuleswithinasectiononDocumentation. Mostcompanieshaveacorporatestandardforsettingupdocumentation,andyouwill,of course,complytothisstandardwhenworkinginacompany. AtDTUwefollowcommontypographicalrulesfortechnicalreports: Puttitleofreport,titleofcourse,date,andyournameandsignatureonthefront WriteonA4sheets. Useaneasilyreadablesizeofcharacters{thefontshouldbeatleast11pt. Usepagenumbering. Themarginsshouldhaveroomforholesusedtoputthereportintoabinder. page. Largerreportsshouldhaveatableofcontentsandanindex. Usepagefootingand/orheadings. Figuresandtablesshouldbenumbered. Chapters,sectionsandsubsectionsshouldbenumbered. run.inparticular,itshouldtellthepotentialuserabout: Theuser'smanualshoulddescribethewayinwhichtheproductshouldbeinstalledand 5.4 Whatproblemthesoftwarecansolvefortheuser.

26 5SOFTWAREPROJECTDOCUMENTATION Howtoinstall,startandstoptheprogram. 26 Whatinputistobeprovidedtotheprograminresponsetoparticularpromptsfrom Thenormaloutputexpectedfromtheprogram. theprogram,orinconnectionwithparticularscreenimages,formsorwhatever.the Anyerrormessageswhichmayappear,whattheymean,andwhattheuserisex- Sourceprogramsshouldbepresentedinamannerwhichmakesitpossibletoseetheir structureandwhichhelpsthereadertounderstandhowtheywork. Thefollowingruleswillhelpyoutoachievethisaim: notation(suchasbnf),sothattheuserisinnodoubtaboutwhatisrequired. inputshouldbedescribedaspreciselyaspossibleinnaturallanguageoraformal 5.5pectedtodoinordertorecoverfrom(oravoid)sucherrors. Starteachmodulewithaheadingintheformofacommentwhichexplainsthe Startthelistingofeachmodule(class,signature,functor,etc.)oftheprogramona purposeofthemodule,whohasprogrammedit,theversionnumberanddateofthe currentversionandotherappropriatedetailswhichcanidentifyit. newpage. Useindentationtohelpthereadertoidentifythebeginningandendofprogram Starteachsub-program(method,function,procedureetc.)ofthemodulewitha structuressuchasloopsandbranchingstructures(if-then-else,case,etc.). anddescribesitsparametersandresults. headingintheformofacommentwhichexplainsthepurposeofthesub-program, Commentsshouldgiveextrainformationwhichcannotbereaddirectlyfromtheprogram, Makesurethatthelinesofprogramtexttwithinthewidthofthepaperanddo suchas: notrunoutovertherighthandmarginoroverowontothenextline. Invariantsofdatarepresentations. Theintendeduseofdeclaredvariables. Theintentionofspecicpartsoftheprogram. Commentsshouldbebriefandtheyshouldnotcluttertheprogram.Theprogrammust bearrangedinawaytomakeiteasyforareadertolocateandndanyspecicpartof theprogram.

27 REFERENCES 5.6 References 27 shouldunambiguouslyidentifythesourceofanyotherdocumentsreferredtointhetext.it isbothillegalandunethicaltoquoteorrefertotheworkofotherauthorswithoutgivinga completeandcorrectreference,sothatthereadercanndtheoriginalmaterialifrequired! Alistofreferencesisanessentialpartofanyscienticortechnicalreport.Thereferences shouldmentionthename(s)oftheauthor(s)(oreditors,iftheworkisacollectionof articlesorthelike),thetitleoftheitembeingreferredtoandthedateofpublication.in abook,conferencepaper,articleinajournal,technicalreportorwhatever.allreferences Theformatofareferencedependsonthetypeofworkbeingreferredto,i.e.whetheritis categoriesofreferences: Book:Author(s)/editor(s),titleofbook,publisher,yearofpublication. moredetail,youshouldgiveatleastthefollowinginformationforthefollowingcommon Articleinbook:Author(s),titleofarticle,titleofbook,chapternumber/pagenumbers, Report:Author,titleofreport,nameoforganisation,year. Journalarticle:Author(s),titleofarticle,nameofjournal,volume,pagenumbers,year. Conferencepaper:Author(s),titleofpaper,nameofconference,pagenumbers,year. youarerecommendedtousesuchasystemifitisavailabletoyou. Sometypicalexamplescanbeseeninthelistofreferencesattheendofthesenotes.Many textformattingsystemsmakeiteasytoproducelistsofreferencesinsuitableformats,and References [Boe95]B.W.Boehm,`TheHighCostofSoftware',inE.Horowitz(ed.),PracticalStrategiesforDevelopingLargeSoftwareSystems.Addison-Wesley,Reading,Massachusetts, [Boe81]B.W.Boehm,SoftwareEngineeringEconomics,Prentice-Hall,EnglewoodClis, NewJersey,1981. [Ris00]HansRischel,`DocumentingSoftware',DepartmentofInformationTechnology, [Som01]IanSommerville,SoftwareEngineering,6thedition.ISBN X. [Roy70]W.W.Royce,`ManagingtheDevelopmentofLargeSoftwareSystems',ProceedingsofWESTCON,California,August1970. DTU,2000. Addison-Wesley,2001.