Megvalósítás
Programozás és kódolás¶
Egy átlagos programozó a munkaidejének 90%-át kód olvasásával tölti.
Bármilyen bolond képes olyan kód írására, amit egy gép megért. A jó programozók kódját más emberek is megértik.
Martin Fowler
Honnan tudom hogy nem "szép" a kódom?
- nehezen tudod régi kódjaidat megfejteni
- sok megjegyzésre van szükséged kódolás közben
- programjaidhoz nagyon nehéz új funkciót illeszteni
- új funkciók hozzáadása után programod más részén érdekes dolgok történnek
Mit tehetek ellene?
Javasoljuk a Tiszta kód elvek követését. Ezenkívül érdemes megérteni és elsajátítani a tervezési minták használatát. A fejlesztés során célszerű figyelni a "bad smell"-ekre majd különböző újratervezési technikákkal javítani a forráskód minőségét.
A szoftverfejlesztés végső célja természetesen a megrendelő igényeinek kielégítése olyan módon, hogy az nyereséges legyen a fejlesztést végző szakemberek számára is. Természetesen a munka során rengeteg jogi, erkölcsi és szakmai elvet is figyelembe kell venni. A szoftverfejlesztés több mint pusztán forráskód írása, de ez természetesen része.
A megrendelők igényei általában követelmény specifikációként kerülnek rögzítésre. A fejlesztő csapat vezetője és más menedzserek ezt tovább bontják a fejlesztők számára is feldolgozható feladatokká, melyeket issue-k formájában rögzítenek. Ezt a folyamatot a gyakorlatvezető végzi el. A hallgatók az issue-kban megfogalmazott feladatoktól veszik át a munkát, mint egy fejlesztő csapat tagjai.
Egy átlagos programozó sokkal több időt tölt hibakereséssel, mint fejlesztéssel.
Szeretem, ha a kódom elegáns és hatékony. A kód logikája egyértelmű kell legyen, hogy nehezen rejtőzzenek hibák a sorok között. A függőségek legyenek minimálisak, mert ez megkönnyíti a karbantartást. A hibakezelés legyen teljes és a kód teljesítménye közel optimális, így nem kísérti az olvasóját további optimalizálásra, amellyel a tisztaságát veszélyezteti. A tiszta kód egy dolgot csinál, és azt jól.
Bjarne Stroustrup
Hogyan fordítsam le a CodeMetropolis-t?
A szoftver rendszerek fordítása (build) összetett sok lépésből álló folyamat. A fordítás során általában három rendszer dolgozik együtt: az operációs rendszer, az automatikus fordító és függőség feloldó rendszer, valamint a fejlesztés alatt álló rendszer maga. Ez közül nyílt forráskódú fejlesztés esetén a fejlesztett projekre erős, a build rendszerre kisebb, míg a fejlesztő operációs rendszerére szinte semmilyen befolyása nincsen a projekt menedzsmentnek. A gyakorlat ilyen (feltehetőleg erősen heterogén) környezetben, hogy legalább egy működő fordítási folyamatot definiál a projekt.
Ez a gyakorlat szempontjából azt jelenti, hogy amennyiben a hallgatók számítógépe megfelel a követelményekben leírtaknak és a projekt által megadott folyamatot követik, úgy a fordítás nagy valószínűséggel sikeresen végbemegy. A hallgatók otthoni gépére (egyéb szoftverek és beállítások) nincs befolyásunk. Természetesen a gyakorlatvezetők tanácsok segítségével iparkodnak majd elhárítani az esetleg egyedi problémákat.
A CodeMetropolis fordítására egy példa az Irinyi Kabinetes gépek kontrolált és steril környezetében itt található. A gyakorlatvezetők saját belátásuk szerint plusz ponttal jutalmazhatják az egyes speciális fordítási hibák és mellékhatások felfedezését és dokumentálását.
Hogyan futtassam a CodeMetropolis-t?
Értékelés¶
Értékelés
A hallgatók a Programozás és kódolás részre 10 pontot kaphatnak. Ebben az alfeladatban teljesíteni kell az elvállalt issue-ban leírt igényeket. A korábbi leadásért a gyakorlatvezető plussz pontot adhat, saját belátása szerint az elvégzett munka minőségét is figyelembe véve. A határidők a naptárban találhatóak, további részleteket a gyakorlatvezető ad a határidő közeledtével.
A fejlesztés GitLab környezetben történik. A futtatható kódot az issue-hoz kapcsolódó feature branch-en kell elhelyezni a Git-ben. Határidőre fordítható, bemutatható kódnak kell lennie, amit videó(ko)n keresztül kell bemutatni. A videó(k) hossza összesen legfeljebb 15 perc lehet. Az elérést lehetővé tévő YouTube linket (videó vagy lejátszási lista) a feladathoz kapcsolódó merge request alá kell beszúrni megjegyzésként. A hallgatóknak ismerniük kell a kapcsolódó issue-k megvalósítása során elvégzett főbb változtatásokat. A bemutatón az implementált változtatásokat, új feature-öket kell bemutatni.
Dokumentáció¶
A fejlesztő feladatai közé tartozik, hogy az általa készített programkódot később tovább lehessen fejleszteni, javítani. A forráskód minősége mellett a rendszer megértéséhez szinte minden esetben szükség van olyan információkra, melyek a megrendelő területéről származnak és nem programozástechnikai jellegűek.
A projektek esetén a fordítottja is igaz. A felhasználó általában nem rendelkezik átfogó informatikai ismeretekkel, vagyis ami a fejlesztő számára egyértelmű az a felhasználó számára sokszor nem az.
Ezeket a többlet információkat a különböző dokumentációk tartalmazzák. A fejlesztők általában saját maguk írják a fejlesztői (kódhoz közelebbi dokumentációt). Továbbá aktívan együttműködnek a PR szakemberekkel a felhasználói dokumentáció elkészítése során.
Fejlesztői dokumentáció¶
Asami Sato továbbképzi az Avatar csapatot
Asami Sato a robottankokat gyártó cég egyik vezető mérnöke. Úgy dönt hogy segít Korra-nak, Mako-nak és Bolin-nak elsajátítani a robottank programozásának alapjait. A lelkes tanulók gyorsan fejlődnek és sok új funkciót kódolnak le. A kódbázis heteken belül a duplájára nő.
Asami egyre több kérdést kap a cég fejlesztőitől, hogy magyarázza el bizonyos algoritmusok működését és osztályok szerepét a kódban. Lassan már arra sincs ideje, hogy az új prototípusok ütemezését átnézze.
Egyik nap Mako rákérdezett egy olyan kódra, melyet még Asami sem értett. A kódott Korra írta, de ő most éppen elutazott a családjához. A fejlesztés megállt. Asami úgy döntött ez így nem mehet tovább. Kötelezővé tette, hogy mindenki csatolja a speciális tudást az általa megírt kódhoz.
A fejlesztői dokumentáció olyan technikai tudást tartalmaz, amely segíti a többi programozót a rendszer továbbfejlesztésében.
De a kód önmagát dokumentálja, nem?
A kód képes bizonyos mértékben leírni és magyarázni, hogy hogyan működik a rendszer. A probléma az hogy általában nem tartalmaz információt arról, hogy miért kell úgy működnie.
Például egy céges adatokat tartalmazó adatbázis tárolhatja a cégek nevét és a telephelyeket. Amíg az kiolvasható az adatbázisból, hogy egy telephely csak egy céghez tartozhat, addig nem lehet tudni, hogy ezt a hatályos jogszabályok, vagy a gyakorlati tapasztalat miatt van-e így, esetleg mindkettő. Ez az információ fontos, hiszen az előbbi esetben a rendszernek követnie kell a jogszabályok változását, míg utóbbinál csak a cég üzletpolitikáját kell figyelembe venni.
Fontos figyelembe venni, hogy a fejlesztői dokumentáció nem csak más fejlesztőknek, hanem saját magunk jövőbeli változatának is segítséget nyújthat.
Segíts magadon (is)!
Mennyi megjegyzést kell írni?
Annyit hogy a kód könnyen érthető legyen egy speciális tudással nem rendelkező fejlesztő számára.
A pontatlan megjegyzések még rosszabbak, mint a megjegyzések teljesen hiánya. A megjegyzések írásának egyik gyakori oka a rossz kód. Érdemesebb inkább rendbe tenni a rossz kódot, mint megjegyzésekkel megtűzdelni. A dokumentálás során az alábbi sorrendet célszerű követni.
- A publikus és protected elemek legyenek dokumentálva, kivétel egy-két triviális eset.
- A kulcsfontosságú vagy összetett privát elemek legyenek dokumentálva.
- A speciális szoftverfejlesztési szaktudást igénylő elemek kerüljenek dokumentálásra. Pl.: miért használtunk egyedi bináris objektum soros-konverziót.
Milyenek a jó megjegyzések?
- Jogi megjegyzések
- Informatív megjegyzések
- Szándékot magyarázó megjegyzés
- Tisztázó megjegyzés
- Következményekre figyelmeztető megjegyzés
- TODO megjegyzés
- Megerősítő megjegyzés
- Javadoc megjegyzés nyilvános API-ban
Milyenek a rossz megjegyzések?
| Fajtája | Leírás | Példa |
|---|---|---|
| Motyogás | hanyagul odavetett megjegyzés, mely legfeljebb a szerzőnek jelent valamit, más számára nem érthető | //TBD |
| Redundáns | nem szolgál semmiféle plusz információval a kódról, nem könnyebb elolvasni sem, mint magát a kódot | // sqrt(i) + 42 / (id % 0x0123BA) |
| Félrevezető | nem eléggé pontos megjegyzés | // ellapsed time (milyen mértékegységben?) |
| Kötelező | a nyilvánvalót magyarázó megjegyzés, ami csak azért van ott, mert megkövetelik, hogy minden függvényhez, változóhoz tartozzon dokumentációs megjegyzés | //the constructor |
| Napló | egy modul elején a benne végzett minden egyes módosítást naplószerűen dokumentáló megjegyzés | //2042-06-01: Creation of the file |
| Zaj-megjegyzés | új információval nem szolgáló, a magától értetődőt újra megfogalmazó megjegyzés | // this method gets the name (string getName() előtt) |
| Pozíciójelző/szalagcím | kód tagolására szokták használni, a legtöbb esetben újratervezéssel a kódban is kifejezhető | // Class Variables |
| Szerző neve | a verziókezelő rendszerek feleslegessé tették | //author: Gergő Balogh |
| Megjegyzésbe tett kód | mások azt fogják gondolni, hogy okkal van ott, fontos, és ezért nem lesz bátorságuk törölni | //i += count % step |
| Nem lokális | olyan megjegyzés, mely nem a közvetlen környezetében lévő kódra vonatkozik | |
| Pletyka | túl sok információt tartalmazó | //base on Pythagorean (born around 570 BC) theorem a^2 + b^2 = c^2 where c is the hypotenuse |
| Nem releváns | kódhoz nem nyilvánvalóan kapcsolódó | //Java virtual machine (JVM) is a virtual machine that enables a computer to run Java programs (adatbázis definíciós fájlban) |
| Rejtett Javadoc | Javadoc megjegyzés nem nyilvános kódban |
Értékelés¶
Értékelés
A Fejlesztői dokumentáció részre a hallgató összesen 8 pontot kaphatnak. A dokumentálás során az egyes kódelemeket Javadoc segítségével dokumentáljuk. Az algoritmusok és folyamatok egyéb részeit hagyományos kommentekkel kell ellátni, ahol a megértéshez a programozástechnikai tudáson túlmutató információra van szükség. Például, miért az adott képletet használta a távolság kiszámítására két épület között a CodeMetropolis Placing fázisában.
Felhasználói dokumentáció¶
A felhasználói dokumentáció célja, hogy segítse a rendszer használatának elsajátítását. Ezt célszerű párhuzamba állítani a fejlesztői dokumentációval, melynek célja a továbbfejlesztés segítése.
A felhasználó nem rendelkezik szoftverfejlesztői, sőt az esetek többségében még informatikai tapasztalatokkal sem. Egy asztalos feladata, hogy meghatározott összegért bútorokat készítsen, nem várható el tőle, hogy ismerje a bankszámláját kezelő rendszer adatbázis-sémáját. A nagymama, aki receptet keres az unokája születésnapjára, nem fogja tudni, hogy a menüben és az ikonsoron lévő gomb ugyan azt az eseménykezelő metódust hívja. A portás, aki Bluetooth-os kamera rendszert használ nem tud sebezhetőségi elemzést futtatni a kódoló algoritmusokon, hogy meggyőződjön róla nem lehet-e lehallgatni a rendszert.
Milyen konverziókat használhatunk a CodeMetropolis Mapping eszközében?
A CodeMetropolis-ban van lehetőségünk, hogy a bemenő adatokat különbözőképpen átalakítsuk a vizualizáció során ezzel javítva az ábrázolás kifejezőképességét. Ezt különböző konverziók segítségével tehetjük meg, melyeket a codemetropolis.toolchain.mapping.conversions csomagban lévő osztályok valósítanak meg.
A rendszer felhasználója itt általában egy fejlesztő vagy kutató, aki szeretné megvizsgálni a forráskód (nem a CodeMetropolis, hanem egy másik rendszer) tuladjonságait. De lehet, hogy nem fér hozzá a forráskódhoz, nem ért "Java-ul" vagy nincs ideje a rendszer belső működését megismernie. A felhasználó csak a hivatalos oldalon lévő dokumentációra támaszkodhat.
A felhasználói dokumentáció megírása nem egyedül a fejlesztő feladata. A fejlesztő birtokában van számos olyan információnak, melyet a dokumentációnak tartalmazni kell, de ezek bemutatása során sok egyéb aspektust is figyelembe kell venni. Ilyen például a termék és a cég marketing céljai és egységes arculata. A terméknek illeszkednie kell az aktuális jogszabályi háttérbe. Végül a vezetők döntése hogy bizonyos funkciókat milyen ütemezéssel és költségekkel tesznek elérhetővé.
De hát ez teljesen egyértelmű! Minek írjam le?
Teszt Elek egész este forgolódott az ágyában. Pár hónapja került be junior fejlesztőként a +Műtlek projekt fejlesztői csapatába. A termék egy új robotkar volt, melyet az olyan műtétek során használnának, ahol a legprofibb sebész keze se tud elég pontos vágásokat ejteni. Számítógépes grafikai tapasztalatai miatt a kar térbeli vezérlésének megtervezésével bízták meg. Az orvos megadja a kulcspontokat, majd a robot megfelelő mozdulatokkal összeköti ezeket.
Álmában a projekt óriási sikert aratott. Bankettek sora követte egymást, s a cég már az Egyesült Államokban is megkezdte az eszköz értékesítését. Elek épp az egyik Floridai értekezleten volt, amikor autóbalesetet szenvedett. Kórházba szállították, ahol már ott várta a műtőben az orvos, a +Műtlek robotkar és az asztalon a használati utasítása. Az orovos belelapozott a vaskos könyvbe.
"az origótól vett távolságot kell megadni" - dünnyögött magában az orvos. - "Nővér, az első bemetszészt a bal felső pontól 1.24 inch-re kezdjük meg. Altatást!"
Elek próbált kiáltani, hogy ne! az origó a jobb alsó pont és minden távolságot mm-ben kell megadni, de ekkor már a maszk a száján volt. S a világ elsötétült.
Teszt Elek remegve ébredt, még félálomban az első dolga az volt, hogy a koordináta rendszerhez kapcsolódó issue alá tett egy megjegyzést: "Felhasználói dokumentációt és követelményeket átnézni: mértékegységek és referencia pontok".
Azt hogy a fejlesztők a felhasználói dokumentációhoz szükséges adatokat milyen formában és módon adják meg az adott cégtől és projekttől függ.
Értékelés¶
Értékelés
A Felhasználói dokumentáció részre a hallgató összesen 7 pontot kaphatnak. A hallgató feladata hogy közvetlenül a választott issue lezárása előtti megjegyzésben röviden összefoglalja az elkészült munka felhasználásának lehetőségét és módjait. A leírásnak a használatra kell koncentrálnia és nem a rendszer belső elemeinek működésére vagy kapcsolataira. Ha az elkészült módosítás eltért az issue-ban megfogalmazott követelményektől, azt részletezni és indokolni kell.
Értékelés összefoglalása¶
| részfeladat | maximális pontszám |
|---|---|
| Programozás és kódolás | 10 |
| Fejlesztői dokumentáció | 8 |
| Felhasználói dokumentáció | 7 |
Értékelés levelező tagozaton¶
| részfeladat | maximális pontszám |
|---|---|
| Programozás és kódolás | 10 |
| Fejlesztői dokumentáció | 10 |
| Felhasználói dokumentáció | 5 |