====== HQedAudit ====== __**Projekt zakończony**__ Łukasz Rachwalski, **Audyt kodu**, dokumentacja, uzupełenie komentarzy w kodzie w języku angielskim, testowanie. Wymagana [[pl:miw:miw08_hqedaudit]]. ====== Spotkania ====== [[https://ai.ia.agh.edu.pl/wiki/pl:miw:miw08_hqedaudit:spotkania|Konsultacje]] ====== Projekt ====== ===== Główne cele projektu ==== - Postawić środowisko uruchomieniowe dla HQed, CVS, DoxyGen. - Uzupełnić dokumentację w kodzie HQed i w wiki. - Przeprowadzić serię testów aplikacji. ===== Co się udało osiągnąć? ===== * Przeprowadzić testy apliacji na przykładach z [[pl:miw:miw08_xtt_serialization]]. * Skomentować wszystkie moduły XTT. * Skompilować hqed w środowisku na własnym komputerze. * Wstępnie zapoznać się z programem jako aplikacją oraz jego kodem źródłowym. * Wygenerować dokumentację na swoim komputerze. * Pobrać projekt ze zdalnego repozytorium (niestety nie charona) i skomentowanie z wykorzystaniem DoxyGen. * Zaznajomić z biblioteką Qt - kompilacja, budowanie prostych aplikacji z wykorzystaniem QtDesigner oraz opcjonalnie QDeveloper. * Zaznajomić się z CVS - uruchomienie na lokalnym komputerze bazy, dodanie projektu, update, check out, diffing, itp. * Poszerzyć znajomość DoxyGen - używanie wyłącznie konsoli, budowa pliku konfiguracyjnego .cfg, generowanie dokumentacji. * Zapoznanie się z obsługą systemu Mantis Bug Tracker - zalogowanie do projektu DEMO, poznanie podstawowych operacji na projektach, poznanie terminologii systemu i sposobu jego działania. * Postawić kompletne środowisko uruchomieniowe. ====== Kompletne środowisko uruchomieniowe ====== ===== W skład kompletnego środowiska uruchomieniowego wychodzą: ===== - System operacyjny: Linux - Ubuntu ver. 7.10. - Concurrent Versions System (CVS) ver. 1.12.13. - Biblioteka Qt ver. 4 - DoxyGen ver. 1.5.3 - Mantis Bug Tracker - HQed ===== Konfiguracja poszczególnych komponentów ===== ==== Ubuntu ver. 7.10 ==== System operacyjny dostępny jest na stronie producenta: [[http://ubuntu.pl/]]. ==== Concurrent Versions System 1.12.13 ==== Producent Ubuntu [[http://ubuntu.pl/]] udostępnił wersje programu do pobrania za pośrednictwem Menedżera pakietów Synaptic. ==== Qt 4 ==== W celu zainstalowania poszczególnych komponentów biblioteki należy wpisać następujące komendy: * sudo apt-get install libqt4-core * sudo apt-get install libqt4-debug * sudo apt-get install libqt4-gui * sudo apt-get install libqt4-qt3support * sudo apt-get install libqt4-sql * sudo apt-get install qt4-designer * sudo apt-get install qt4-dev-tools * sudo apt-get install qt4-doc * sudo apt-get install qt4-qtconfig Edytor bądź środowisko programistyczne to już kwestia gustu i wygody programisty. Poniżej umieszczono jednak przykładowe aplikacje. * [[http://www.qdevelop.org]] - QDevelop środowisko które połączone jest z komponentami bilioteki Qt m.in. z QtDesigner. * [[http://www.eclipse.org/]] - Kompletne środowisko programistyczne dedykowane językowi Java. Wymagana jest instalacja środowiska uruchomieniowego Java. Ponadto należy dograć mechanizm obsługi C/C++ - CDT. Można to zrobić w sposów następujący [[http://cs.calvin.edu/curriculum/cs/112/resources/installingEclipse/cdt-3.3/]]. Źródło powyższych informacji to: [[http://www.clivecooper.co.uk/tutorial/index.html]]. ==== DoxyGen 1.5.3 ==== Producent Ubuntu [[http://ubuntu.pl/]] udostępnił wersje programu wraz z dokumentacją oraz nakładką graficzną do pobrania za pośrednictwem Menedżera pakietów Synaptic. ==== Mantis Bug Trucker 1.1.1 ==== Mantis Bug Trucker to darmowy system raportowania błędów powstałych podczas procesu tworzenia oprogramowania. Można go pobrać ze strony producenta [[http://www.mantisbt.org/]]. Został napisany w języku PHP i współpracuje z MySQL. Dzięki temu można go używać na wielu platformach m.in. Linux, Windows, Mac OS, OS/2. ====== Komentowanie źródeł projektu ====== ===== Struktura katalogowa projektu ===== Założono, że komentowniu podlegają tylko te moduły, które znajdują się w katalogach o nazwie XTT. Poniższy schemat zawiera podział katalogowy aplikacji HQed. Hqed |--C |--ARD |--XTT /// zawiera moduły do skomentowania M |--ARD |--XTT /// zawiera moduły do skomentowania V |--ARD |--XTT /// zawiera moduły do skomentowania ===== Założenia dotyczące wstawiania komentarzy ===== * Styl komentowania w [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|DoxyGen]]: JavaDoc. * Komentowane są tylko pliki nagłówkowe. * Język komentarzy to angielski. ===== Skomentowane moduły ===== * Kompletna dokumentacja projektu HQed znajduje się [[https://hekate.ia.agh.edu.pl/webdoxy/hqed/doc/|tutaj]]. ===== Podsumowanie ===== Podczas realizacji projektu skomentowano 43 pliki nagłówkowe redagując 43 pliki cpp. Czas komentowania jednego pliku wahał się od ok. 1 godziny do 5-6 godzin. Po skomentowaniu wszystkich modułów dokonano ponownego przeglądu źródeł i niewielkich poprawek. ====== Testowanie aplikacji ====== Testy przeprowadzono na przykładach zaczerpniętych z [[pl:miw:miw08_xtt_serialization]]. ===== Test Funkcjonalności Aplikacji HQed ===== Testy funkcjonalności znajdują się {{:pl:miw:protokul_testu_hqed.pdf|tutaj}}. ===== Test 1 - Cennik biletów na wyciąg narciarski ===== - Wygenerowany Xttml: {{:pl:miw:wyciag_narciarski.xttml|Wyciag_narciarski.xttml}}. - Uwagi: * program czasem błędnie interpretuje typ enumerate * program nie posiada możliwości wprowadzenia operatora: ALL oraz ANY w edycji komórki ===== Test 2 - Ceny biletów na pociąg ===== - Wygenerowany Xttml: {{:pl:miw:bilety_na_pociag.xttml|Bilety_na_pociag.xttml}}. - Uwagi: * program czasem błędnie intrpretuje wprowadzony typ enumerate ===== Podsumowanie ===== Aplikacja została dość szczegółowo przetestowana. Wynik testów jest jednak pozytywny. Program działa dobrze, jest stosunkowo stabilny a istniejące błędy są jedynie niedociągnięciami których usunięcie nie powinno być kosztowne. ====== Podsumowujące sprawozdanie z projektu ====== Tematem projektu HQedAudit był audyt kodu aplikacji HQed. Audyt ten polegał na analizie i komentowaniu kodu programu w języku angielskim. Ponadto projekt przewidywał testowanie i zgłaszanie błędów aplikacji w systemie [[https://hekate.ia.agh.edu.pl/webtrac/hades/trac.vc|CVStrack]]. Realizacje projektu rozpoczęto od analizy źródeł HQed. Kod programu napisany został w języku C++. Do stworzenia interfejsu użytkownika (GUI) wykorzystano bibliotekę Qt w wersji 4. Autor HQed wprowadził również katalogowy podział źródeł na XTT oraz ARD. Zgodnie z poleceniem prowadzącego skomentowano tylko pliki znajdujące się w katalogach XTT. Następnie przystąpiono do komentowania źródeł. Proces ten przebiegał w następujący sposób. Na początku dokonano pobieżnej analizy metody w pliku cpp, a następnie na podstawie wyciągniętych wniosków komentowano nagłówek. Na słowa pochwały zasługuje autor aplikacji, który napisał kod bardzo przejrzysty oraz w dużej mierze skomentowany. Bardzo to uprościło pracę nad audytem kodu jednak nie wykluczyło przeprowadzonej analizy źródeł i potwierdzenia zapisanych informacji. W procesie komentowania przyjęto następujące założenia: * Komentowano tylko pliki nagłówkowe. * Jako generatora dokumentacji użyto DoxyGen. * Wykorzystano JavaDoc jako styl komentowania. Wszystkie komentarze plików nagłówkowych zostały zapisane w języku angielskim. Po skomentowaniu dowolnego modułu dokonywano kompilacji całej aplikacji oraz próby jej uruchomienia. Dokonywano bowiem zmian zarówno w pliku *.cpp jak i *.h. Pracując na źródłach pobranych z repozytorium za pośrednictwem [[http://furryland.org/~mikec/cvs.html|CVS]] wprowadzano wiele zmian. Starano się również aby kod który wysyłano z powrotem do repozytorium nie zawierał błędów. Proces komentowania kodu przebiegał w sposób systematyczny. Na cotygodniowych konsultacjach raportowane były postępy w pracach. Ponadto uzgadniano szczegóły co do planowanych zmian. Podczas realizacji projektu skomentowano 43 pliki nagłówkowe redagując 43 pliki cpp. Czas komentowania jednego pliku wahał się od ok. 1 godziny do 5-6 godzin. Po skomentowaniu wszystkich modułów dokonano ponownego przeglądu źródeł i niewielkich poprawek. Program został skompilowany oraz uruchomiony na Ubuntu wersji 7.10. Dzięki uprzejmości do testu finalnego wykorzystano [[https://ai.ia.agh.edu.pl/wiki/_media/pl:miw:miw08_ardcase_cs:cashpoint-xttml_v3.xttml?id=pl%3Amiw%3Amiw08_ardcase_cs%3Abankomat&cache=cache|bankomat_xttml]]. Wszelkie potencjalne błędy, sugestie zgłaszano autorowi poprzez system raportowania błędów [[https://hekate.ia.agh.edu.pl/webtrac/hades/trac.vc|CVStrack]]. Aplikacja została gruntownie przetestowana. Wykonano testy funkcjonalności mające na celu sprawdzenie czy program posiada funkcje umożliwiające generowanie i zarządzanie diagramami XTT. Testy te wypadły dość dobrze. Aplikacja co prawda posiada kilka niedociągnięć, są one jednak na tyle nieszkodliwe, że nie uniemożliwiają pracy w HQed. Ponadto wykonano testy polegające na wprowadzeniu dwóch systemów regułowych. Wprowadzano je od zera i generowano pliki XTT. HQed przeszedł pomyślnie również tę partię testów. ====== Materiały pomocnicze ====== **1. CVS** * [[http://www-mrsrl.stanford.edu/~brian/cvstutorial/]] - całkiem nieźle napisany tutorial dla początkujących, zawiera liczne przykłady użycia podstawowych funkcji CVS. * [[http://cvsbook.red-bean.com/cvsbook.html#A%20Day%20With%20CVS]] - książka "Open Source Development with CVS, 3rd Edition" autorstwa Karl Fogel i Moshe Bar, obszernie opisująca CVS. * [[http://www.nongnu.org/cvs/]] - stąd można pobrać program oraz znaleźć liczne odwołania do literatury. **2. Qt** * [[http://trolltech.com/products/qt]] - wszystkie potrzebne informacje z zakresu biblioteki Qt. **3. DoxyGen** * [[http://www.stack.nl/~dimitri/doxygen/]] - manual, FAQ's oraz inne informacje dotyczące DoxyGen. **4. Mantis Bug Trucker** * [[http://www.mantisbt.org/]] - darmowe wersje release systemu Mantis, manual oraz wiele użytecznych materiałów.