Merge pull request #37 from BME-MIT-IET/doc

Doc

doc/IET munkanapló sablon.typ

@@ -0,0 +1,125 @@
+#set text(lang: "hu")
+
+#let todo(x) = text(red)[#x]
+
+#show link: set text(rgb(0,0,255))
+#let gh(x) = link("https://github.com/" + x)[#x]
+
+
+= Házi feladat munkanapló: Bubogók
+Integrációs és ellenőrzési technikák (VIMIAC04)
+
+#block(breakable: false)[
+== Csapattag 1 (Koczó Attila István, ITWQ3V, #gh("koczoa"))
+=== Statikus analízis (összesen kb. 5 óra):
+
+- A kód összevetése a követelményekkel.
+
+=== Hibajavítás (összesen kb. 5 óra):
+
+- A kódban előzetesen ismert lényegesebb hibák javítása.
+
+=== Code review (összesen kb. 5 óra):
+
+- A többi csapattag által írt kód felülvizsgálata.
+
+]
+
+#block(breakable: false)[
+== Csapattag 2 (Sandle Nátán, SGGDSK, #gh("darpleon"))
+=== Python unit tesztek (összesen kb. 6 óra):
+
+- Unit tesztelési lehetőségek felmérése
+- Unit tesztek implementálása
+
+=== Java unit tesztek (összesen kb. 7 óra):
+
+- Unit teszteléshez kapcsolódó függőségek kezelése
+- Mockito használatának elsajátítása
+- Unit tesztek tervezése
+- Unit tesztek implementálása
+
+=== Code review (összesen kb. 2 óra):
+- A többi csapattag által írt kód felülvizsgálata.
+]
+
+#block(breakable: false)[
+== Csapattag 3 (Szarkowicz Dániel, FK0IEH, #gh("daniel-szarkowicz"))
+=== Python github actions (összesen kb. 2 óra):
+
+- Példa tesztelhető modul és példa teszt elkészítése
+- Github actions megírása
+
+=== Szálak helyes leállítása (összesen kb. 7 óra):
+
+- Probléma megismerése
+- Különböző Java módszerek összehasonlítása
+- Shutdown hookok implementálása
+
+=== Code review (összesen kb. 2. óra):
+
+- A többi csapattag által írt kód felülvizsgálata
+- Kód elutasítása javítási javaslatokkal
+
+=== Logger (összesen kb 3. óra):
+
+- Apró hibák kijavítása
+- Színes labelek implementálása
+- Print-ek loggerre cserélése
+
+=== Pair programming (összesen kb 3. óra):
+
+- Gradle fáljok írása (cucumber)
+]
+
+
+#block(breakable: false)[
+== Csapattag 4 (Szombati Olivér, P37PLU, #gh("Szombatioi"))
+=== Github Actions (összesen kb. 3 óra)
+- gradle.yaml fájl elkészítése
+
+=== Logger (összesen kb. 6 óra):
+- Osztályhierarchia megtervezése
+- Implementáció elkészítése
+- Naplózási formátum megtervezése
+- Konzolra írások átírása naplózásra
+
+=== Java unit tesztek (összesen kb. 4 óra):
+- FieldTest tesztesetek megtervezése + leírása
+
+=== Code review (összesen kb. 2 óra):
+- Csapattársak PR-jainak ellenőrzése
+- Módosítási javaslatok tétele
+
+]
+
+#block(breakable: false)[
+== Csapattag 5 (Tamási Máté, ONYGW3, #gh("matetamasi"))
+=== Cucumber (összesen kb. 9 óra):
+
+- Specifikáció megfogalmazása
+- Java lépésdefiníciók leírása
+- Gradle task létrehozása és hozzáadása github actions-höz
+
+=== SonarCloud beállítása (4 óra):
+
+- Gradle task létrehozása
+- Github action létrehozása
+- Élő statisztikák hozzáadása a README-hez
+- Coverage ellenőrzés kikapcsolása
+
+=== Code review (összesen kb. 2 óra):
+
+- PR-beli kód statikus vizsgálata
+- PR-beli kód helyi futtatása
+]
+
+2024-05-22
+
+#v(1cm)
+
+#(28 * ".") #math.quad
+#(28 * ".") #math.quad
+#(28 * ".") #math.quad
+#(28 * ".") #math.quad
+#(28 * ".") #math.quad

doc/githubActions_Gradle.md

@@ -0,0 +1,5 @@
+# Java Github Actions gradle fájl
+
+A github-on való kódellenőrzéshez szükséges volt egy `gradle_tests.yaml` fájlt elkészíteni a `.github/workflows` mappába.
+
+Ez a fájl azt írja le, hogy minden pull request és push során futtassa le a Java teszteket a Github felületén.

doc/graceful_exit.md

@@ -0,0 +1,5 @@
+# A szálak helyes bezárása
+
+A program a kommunikációhoz és a rajzoláshoz számos szálat használ. Ha a szálak rosszul állnak le, akkor az inkonzisztens fáljokhoz vezet, ha a program ír fáljokba.
+
+A szálak garantált leállásához a Java shutdown hook használható. A shutdown hookok a JVM leállításakor automatikusan meghívódnak. Sajnos a Gradle nem állítja le rendesen a JVM-et, ezért a shutdown hookok nem hívódnak meg. Ez szerencsére élesben nem lesz probléma, mert a kész szoftvert a `java -jar` parancssal kell majd futtatni és az rendesen fogja leállítani a JVM-et.

doc/javaUnitTest.md

@@ -0,0 +1,6 @@
+## Java unit tesztek
+
+A kód javában írt részének teszteléséhez a JUnit Jupiter és Mockito könyvtárakat használtuk.
+A Position, Field, és Team osztályok kerültek tesztelésre.
+
+A unit tesztjeink célja az egyes osztályok alapvető működésének tesztelése. A tesztek során Mock objektumok helyettesítették a teszt számára irreleváns objektumokat.

doc/logger.md

@@ -0,0 +1,16 @@
+# Logger osztályok
+
+A programban a naplózásokat megvalósítandó **Logger** osztályok állnak rendelkezésre, melyekkel lehet `file`-ba, `console`-ra, illetve egyéb `PrintStream` típusokba naplózást írni.
+
+## Naplózási szintek
+Négyféle naplózási szintet különböztetünk meg:
+- debug
+- info
+- warning
+- error
+
+## Naplózott információ
+Naplózás során vannak statikus (dátum, naplózási szint, hívó osztály és függvénye) és dinamikus (`label`, ami a naplózás célját foglalja össze, illetve `message`, mely egy akár többsoros üzenetet reprezentál) adatok, amiket kiírunk.
+
+## Naplózás menete
+A naplózáshoz a `Log` osztály használandó, mely szinkronizáltan több forrásból is tud naplózási kéréseket fogadni, illetve cserélhetően tárolja az aktív Logger implementációt.

doc/pythonUnitTest.md

@@ -0,0 +1,7 @@
+## Python unit tesztek
+
+A kód pythonban írt részének teszteléséhez a standard librarys unittest modult használtuk.
+A pos és mapPart elemekre készült unit teszt.
+A mesterséges intelligencia tesztelésére a unit teszt nem volt alkalmas.
+
+A mapPart tesztelésekor egy egyszerű saját UnitView mockot használunk.

doc/python_github_actions.md

@@ -0,0 +1,6 @@
+# Pythonos github action
+
+A szoftver mesterséges intelligencás része pythonban íródott. A Pythonos kódot is tesztelni kell, sőt a Python érdekes tulajdonságai miatt fontosabb, mint a Javat. A legjobb, ha a tesztek automatiksan futnak minden pull requesten.
+
+A github actionssel könnyű volt beállítani az automatikus ellenőrizni, a tesztek futtatásáhos a Python unittest moduljának a `discover` parancsát használjuk.
+

doc/sonarCloud.md

@@ -0,0 +1,9 @@
+# Statikus analízis 
+
+## Manuális kódvizsgálás
+Manuális kódvizsgálás során a kód nehezebben érthető részeit részletesen, csapatszinten átolvastuk, részben, hogy mindenki gyorsan és viszonylag akadálymentesen megértse a már meglevő kódokat, részben, hogy egy alap manuális kódátvizsgálást is végezzünk.
+
+## Automatikus kódvizsgálás
+Míg a manuális kóvizsgálás elengedhetetlen része a jól működő kódnak (hiszen egy gép nem, vagy csak kevéssé érti meg, hogy az adott kódrészelet mit szeretne csinálni), addig a clean code és egyéb elvek betartását ma már nagy nyugalommal bízhatjuk gépekre, hiszen így a fejlesztők valós időben kaphatnak visszajelzést arról, hogy az éppen írt kód milyen minőségű. \
+Ebben nyújt segítséget a pl. a Sonar termékcsalád is, ami a teljes körű CI/DI kódellenőrzést végez. \
+A házi feladat során a SonarCloud szolgáltatást és SonarLint kiegészítőt használtuk, előbbit github actions segítségével automatizáltuk. Először a már meglévő kódbázist vizsgáltattuk, majd a kapott hibákat súlyosság szerinti prioritás alapján rendeztük és szűrtük. Ezek közül a legfontosabbakat kijavítottuk. A kódon eszközölt további javítások, tesztek és bővítések pedig már a SonarCloud és a SonarLint használata mellett készültek. A legmeglepőbb számomra a "cognitive complexity" volt, ami a kezdeti kódbázisban egy alkalommal 85 volt az elfogadható 15 helyett, azonban a harmincas-negyvenes complexity-k is gyakoriak voltak. Java oldalon minden ilyen jellegű hibát kijavítottunk, valamint számos más, a SonarLint által javasolt dolgot is módosítottunk, hogy minél inkább kövesse a projekt a clean code elveket.