Kuidas kirjutada efektiivseid vearaporteid?
01.12.2008 | GunnarHeade vearaportite koostamine pole kerge. Kes meist poleks kokkupuutunud üliinformatiivsete teadatega stiilis ma-ei-tea-programm-andis-mingi-vea. Sellise infoga pole enamasti kellelgi midagi peale hakata ja kui arendajad pole loonud head vigade käsitlemise ja raporteerimise tuge süsteemile, siis hakkab pihta ajaliselt kulukas mõistatamine - mis võis juhtuda selles kohas, et tuli viga? Korralikud vearaportid võivad taolised ajakulud peaaegu nullida ja seepärast kirjutasin ka selle kande. Suunatud on see peamiselt tavakasutajatele, kes oma igapäevases töös mõnda firma jaoks loodud süsteemi peavad kasutama.
Vigade raporteerimine pole ühepoolne rutiin, mille tellija välja peab töötama. Efektiivne raporteerimise kord pannakse paika arendaja ja tellija ühistööna. Järgnev nimekiri soovitustest pärineb Frank Kelly blogi kandest How to file a good bug report. Et minu soovituse kohaselt on tegemist koostööga arendaja ja tellija vahel, siis lisan juurde omapoolsed kommentaarid, et protsess kujuneks valutumalt. Lisaks tegin soovitustesse mõned omapoolsed muudatused sisse.
1. Kirjuta vea kohta informatiivne kokkuvõte
Kokkuvõte ei pea olema pikk ja ülipõhjalik. Oluline on anda lühidal kujul ülevaade veaolukorrast - kus viga tekkis ja mille peale viga tekkis. Et tihti hakkab veale reageerimine arendaja poolel pihta sellest, et veaga tegeleb esimesena kas tehniline tugi või projektijuht, siis nende jaoks on põgus ja ülevaatlik kirjeldus tihti piisav. See annab neile aimu, millises süsteemiosas viga tekkis ja mis laadi võiks viga olla.
Suurema töötajate arvuga firmades aitab see lähenemine vältida seda, et viga satub suurde surnud ringi, kus seda kuuma kartulina üksteisele veeretatakse, sest kiire on ju kõigil. Kui on selge kasvõi umbkaudu, et mis ooperist antud viga on, siis on ka inimestering, kellele veaga tegelemine delegeeritakse, oluliselt pisem.
2. Raporteeri programmi täpne versioon, mida kasutad
Töölaual töötavate rakenduste korral on versioon oluline. Samuti on versioon oluline siis, kui on tegemist veebipõhise süsteemiga, millest on kasutusel erinevaid versioone või mille tootja on andnud süsteemist välja erinevaid versioone.
Enamasti ei tea lõppkasutajad, kus kohast versiooni vaadata. Töölaua rakendustega on lihtne - versioon on kirjas About aknas. Veebipõhistes süsteemides aga tavaliselt sellist menüüd pole ja seda infot pole ka lehekülgede jaluses (kas või pisikeselt) kirjas.
Minu soovitus arendajatele on selline. Tehke ka veebipõhise süsteemi versioon lihtsasti kättesaadavaks. Pange see lehe jalusesse või tehke eraldi fail, kust versiooni saab välja lugeda. Oluline on see, et kasutaja ei peaks tegema tema jaoks keerukaid liigutusi. See, et viga tekkis, segas tema tööd juba niigi palju.
3. Raporteeri tehnilise keskkonnaga seonduv
Kirjutage raportisse süsteemi jooksutava tehnilise keskkonna näitajad nagu näiteks:
- operatsioonisüsteem ja selle versioon,
- andmebaasiserver ja selle versioon,
- sammud, mida tegid süsteemi paigaldamisel,
- kasutajakonto, mille all viga tekkis ja antud konto õiguste tase.
Alati võib leiduda vigu, mis on kinni tehnilises keskkonnas. Näiteks programm, mis töötab veatult Windows XP peal, võib tekitada vigu Windows Vista või mõne muu Windowsi peal. Samuti võib olla probleem kasutajale puudulikult antud õigustes, mida programm ise ei suuda korrektselt kontrollida.
4. Mida tegid, et viga tekkis?
See on nüüd see kõige valusam koht, sest ikka läheb arvuti ise rikki ja programm puruneb omal algatusel tuhandeks killuks ja see kõik juhtub perfektses korras arvutis. Süüdi saab olla ainult üks - arendaja!
Muideks, see on küllaltki tüüpiline olukord. Sellist valetamist tuleb suhteliselt palju ette. Tegelikkuses võivad aga programmi viia töökorrast välja näiteks “meeldivad lisandid” kasutaja arvutis nagu igasugu nuhkvara ja viirused, mis mõjutavad operatsioonisüsteemi erinevaid osi. Samuti on võimalik, et kasutaja tegi arvutisse omal algatusel ruumi juurde ja selle käigus kadus ära terve rivi programmi tööks vajalikke faile.
Et arendaja saaks paremini vigadele jälile, tuleb talle anda piisavalt infot. Vastasel korral peab arendaja hakkama pimesi viga taastootma. Kui tegemist on harva esineva veada, mis tekib ainult mingitel spetsiifilistel tingimustel, siis sellise vea taastootmine võib aega võtta ka nädalaid. Viitsite oodata nii kaua ja olete kindel, et parandustele järgnev hooldustööde arve viib teie suunurgad kõrvade taha? Vaevalt.
Selleks, et arendaja saaks veaga tegeleda, on tal vaja teada, mida kasutaja tegi ja kuidas ta tegi, et viga tekkis. Oluline on teada sedagi, et mis oli antud hetkel vormi väljadele sisestatud. Ühesõnaga, mida rohkem suudab vea tuvastanud kasutaja anda arendajale infot, seda parem. Rõhutan veelkord - nii võib aega kokku hoida nädalaid.
5. Lisa vearaportile täiendav info
Kui viga tuleb, siis on kasulik anda selle kohta mitmekülgset informatsiooni. Kindlasti võib vearaportile lisada ekraanpaugu, kus on näha programmi aken või aknad koos tekkinud veaga. Ekraanpaugu tegemine on lihtne - klaviatuuril on olemas nupp, mille peale on kirjutatud PrtScr, PrtSc või Print Screen. Peale selle nupu vajutamist ava näiteks Paint, vajuta pasteerimise nuppu ja salvesta pilt.
Kui programm koostab tehnilisi logisid, siis võib vearaportile lisada ka viimase logifaili. Logi võib sisaldada arendaja jaoks äärmiselt olulist infot. See info näeb lõppkasutaja jaoks ehk välja nagu suvaline tähemärkide pudru, kuid arendajale võib see pudru anda kohese vastuse probleemi kohta.
Lõpetuseks
Vigade raporteerimine seisneb suuresti selles, et vea tuvastanud kasutaja annab arendajatele edasi põhjaliku info veaolukorra kohta. Seda tehakse kokkulepitud kanali kaudu ning arendajatele jagatakse infot eelnevalt kokkulepitud formaadis. Vea tuvastanud kasutaja ei tohi ennast tunda süüdlasena - ta ei tohi sattuda patuoina rolli, kes süsteemi kogemata katki tegi.
Kui vearaportid on arendajate jaoks informatiivsed, siis saavad arendajad hakata koheselt tegelema vea likvideerimisega. Kõige ajaliselt kulukam vea teade on see maailma lühim: programm ei tööta.