8.7 Kódbázis navigáció és onboarding egy új projektben

Áttekintő

Képzeld el, hogy egy idegen városba érkezel, térkép nélkül, és azt mondják: „Holnaptól itt dolgozol, az irodát megtalálod." Ez az érzés vár rád az első munkanapod utáni második héten, amikor odaülnek elé egy ismeretlen kódbázisnak, és azt mondják: „Nézd meg, értsd meg, aztán csináld ezt a ticketet."

A legtöbb junior fejlesztő ezen a ponton ugyanazt csinálja: megnyitja a legelső fájlt, amit talál, belezuhan a kódba, és egy óra múlva még mindig nem érti, hogy mi a fő belépési pont. Ez nem tudáshiány – ez módszertani hiány.

Ebben az alfejezetben megtanulod, hogyan térképezz fel szisztematikusan egy ismeretlen projektet, hol keress belépési pontokat, mikor kérdezz és mikor deríts fel önállóan, és hogyan húzd ki a legtöbbet az első heteidből – beleértve az első PR stratégiát is.

Részletes leírás

Az ismeretlen kódbázis nem ellenség – térkép nélküli város

Az ismeretlen kódbázis feltérképezése nem arról szól, hogy megértsd az összes kódot. Arról szól, hogy megértsd a projekt struktúráját, a kapcsolatokat és a szándékokat – és ezt fokozatosan teszed, nem egy nap alatt.

Két véglet létezik, amit érdemes elkerülni:

Passzív várakozás: „Valaki majd elmagyarázza." → Senki nem fog végigvezetni minden fájlon.
Vak merülés: Megnyitsz egy random fájlt és olvasni kezded → Kontextus nélkül értelmetlen.

A helyes megközelítés: top-down feltérképezés, bottom-up mélyülés.

1. lépés – A README és a dokumentáció (nem kihagyható)

Az első 30 percedben a kódot ne nyisd meg. Helyette:

Olvasd el a README-t – Ha jól írták, megmondja: mi ez a projekt, hogyan indítsd el, és mi a belépési pont.
Keresd a docs/ vagy wiki mappát – Architekturális leírások, ADR-ek (Architecture Decision Records), onboarding guide.
Nézd meg a CHANGELOG-ot – Mi változott az utóbbi időben? Mi a projekt iránya?
Futtasd a teszteket – Ha vannak tesztek és futnak, az sokat elárul a kódbázis egészségéről.

Ha a README hiányos vagy nincs – ez maga is információ. Jegyezd fel, és a saját onboarding notes-unkba kerül.

2. lépés – Belépési pontok megtalálása

Minden projektnek van egy „ahol a program elindul" pontja. Ez projekttípusonként különbözik:

Típus	Belépési pont jelölés
Python alkalmazás	`main.py`, `app.py`, `wsgi.py`, `manage.py`
Node.js / JavaScript	`index.js`, `server.js`, `app.js`, a `"main"` mező `package.json`-ban
PHP / Laravel	`public/index.php`, `artisan` CLI
Általánosan	A `Makefile`, `docker-compose.yml`, `scripts/` mappa vezet ide

Amit keress: Hol indul el az alkalmazás? Melyik fájlt hívja meg a szerver? Melyik paranccsal indítják? Ez általában a package.json scripts szekciójában, a Makefile-ban, vagy a CI konfigurációban (.github/workflows/, Jenkinsfile) megtalálható.

3. lépés – Fájlstruktúra megértése, nem olvasása

Ne kezdj el minden fájlt megnyitni. Ehelyett nézd meg a mappák nevét és gondolkodj el rajta:

project/
├── src/            → itt van a fő kód
│   ├── models/     → adatmodellek, DB struktúrák
│   ├── controllers/ vagy handlers/ → HTTP kérések kezelése
│   ├── services/   → üzleti logika
│   └── utils/      → segédfüggvények
├── tests/          → tesztek
├── config/         → konfigurációs fájlok
├── docs/           → dokumentáció
├── scripts/        → automatizált szkriptek
└── .github/        → CI/CD konfiguráció

A fájlstruktúra megmondja, milyen architektúrát használ a projekt (MVC, hexagonális, feature-alapú stb.) anélkül, hogy egyetlen kódsort olvasnál.

Feladat önmagadnak: Mielőtt bármit olvasnál, írd le 5 mondatban, amit a mappastruktúrából következtetsz. Aztán nézd meg, mennyit sikerül megerősíteni.

4. lépés – Dependency graph olvasása

A projekt package.json, requirements.txt, composer.json (vagy egyenértékű) fájlja nem csak csomaglista – elmondja, milyen problémákat old meg a projekt.

Nézd meg:

Mik a fő függőségek? Melyik framework-öt használják? (Express, Django, Laravel, Spring stb.)
Van-e tesztelési keretrendszer? (Jest, pytest, PHPUnit)
Van-e linter / formatter? (ESLint, Prettier, Black, PHP-CS-Fixer)
Van-e ORM / adatbázis library? (Sequelize, SQLAlchemy, Eloquent)

Ezek együtt festik le a technológiai stacket, mielőtt bármit kézzel futtatnál.

5. lépés – Git history mint térkép

A git log az egyik legjobb dokumentáció, amit egy projekt nyújthat – és legtöbben elfelejtik megnézni.

git log --oneline -20        # utolsó 20 commit röviden
git log --stat -10           # melyik fájlok változtak sokat
git shortlog -sn             # ki dolgozik sokat ezen a projekten

Amit keress:

Melyik fájlok változnak a legtöbbet? Ezek az aktív fejlesztési területek.
Ki a legaktívabb contributor? Ők lesznek a legjobbak kérdezni.
Vannak-e commit-ek, amik sok fájlt érintenek egyszerre? Nagy refaktorálások, architektúra váltások.

6. lépés – Mikor kérdezz, mikor deríts fel önállóan?

Ez az egyik legnehezebb döntés juniorként, és valójában mindkét véglet baj:

Túl sokat kérdezel → Zavarod a csapatot, nem mutatod meg, hogy képes vagy önállóan dolgozni.
Túl keveset kérdezel → 2 napot töltesz valamivel, amit 5 percben megmagyaráztak volna.

Az ökölszabály: 20 perc

Ha 20 percnél tovább nem tudsz haladni egy kérdés miatt, kérj segítséget. De készülj fel a kérdéssel:

„Ezt próbáltam: [...]"
„Eddig jutottam el: [...]"
„Azt feltételezem, hogy [...], de nem látom, hol van az X."

Ez megmutatja, hogy dolgoztál rajta, és a kérdés is sokkal pontosabb lesz.

Onboarding-specifikus kérdések: Ezeket MINDIG tedd fel, ne halaszd:

„Mi az első PR-hoz ajánlott scope?"
„Van-e onboarding dokumentum?"
„Kire kell figyelni code review-nál?"
„Van-e valami, amit a README nem mond el, de kellene tudnom?"

7. lépés – Saját onboarding notes

Az onboarding ideje alatt szerzett tudás hamar elillan. Amit most nehéznek tűnik megérteni, 3 hét múlva triviálisnak fog tűnni – de a következő kolléga pontosan ugyanolyan nehézséggel fog küzdeni.

Tarts saját feljegyzéseket:

Mit értettél meg, hogyan? (Pl. „Az auth flow: [leírás]")
Hol akadtál el és mi oldotta meg?
Melyik fájlban mi van? (Saját szavaiddal)
Mik a nem dokumentált konvenciók? (Pl. „Mindig X stílusban nevezzük a service-eket")

Ez három dolgot ad:

Megerősíti a tudásod (aktív feldolgozás)
Később referencia lesz
Ha egyszer kérik, hogy segíts onboarding-olni az újabb juniorokat – már kész van

8. lépés – Az „első PR" stratégia

Az első PR-od az első benyomásod a csapat felé. Két véglet van:

Túl nagy → Nehéz reviewolni, sok a feedback, elveszíted a motivációt.
Triviális csak azért → Nem mond semmit a képességeidről.

Az ideális első PR:

Kis méretű (néhány fájl, néhány tucat sor)
Jól körülhatárolt (nem nyúl bele sok mindenbe)
Van benne némi valódi értelem (nem csak typo fix – bár az is elfogadható kezdésnek)
Lehetőleg van hozzá teszt – még ha a projekt nincs tele tesztekkel, az első PR-ban írni egyet nagyon pozitív jel

Tipikus első PR jelöltek:

Kis bug fix, amivel amúgy is találkoztál onboarding közben
Dokumentáció javítás (amit te hiányoltál)
Egy hiányzó teszt megírása
Kis refaktor, amit a csapat jóváhagyott

Mielőtt megnyitod a PR-t: kérd meg az egyik kollégádat, hogy nézze meg informálisan, mielőtt offical review kérés megy ki. Ez normális és elfogadott szokás.

Életszerű példák

Példa 1 – A random fájl csapda

Béla első napján megnyitja a projektet és elkezd olvasni: UserController.php. Fél óra múlva azt látja, hogy a UserController meghív egy AuthService-t, az egy TokenRepository-t, az meg egy CacheManager-t. Elveszett.

Anna ugyanazon a napon megnézi a mappastruktúrát, a README-t, majd a routes/ mappát – mert tudja, hogy egy web alkalmazásban az útvonalak mondják meg, mi van. 20 perc alatt érti az alkalmazás fő funkcióit, és utána már célzottan nyitja meg a UserController-t, mert tudja, melyik route hívja.

Példa 2 – A git log titka

Csaba onboarding közben megnézte a git log-ot és meglátta, hogy az orders/ mappa az elmúlt két hétben 47 commitot kapott. Feltette a kérdést: „Látom, hogy az orders modul nagyon aktívan fejlődik – van folyamatban lévő nagy változtatás, amit tudnom kellene?" A válasz: „Igen, éppen migrálunk egy új fizetési providerre, erről szólt volna egy meeting, de te nem voltál még ott."

Ez az egyetlen kérdés megmentett neki napokat felesleges munkától.

Példa 3 – Az onboarding notes értéke

Dóra minden nap 10 percet töltött onboarding notes írásával az első két héten. Amikor 3 hónappal később egy új junior csatlakozott a csapathoz, Dóra 2 óra alatt átadta a notes-ait – és ezzel spórolt 2-3 napnyi random kérdezést.

A tech lead észrevette, és a következő sprint reviewon kiemelte, mint példát arra, hogyan kell tudást átadni.

Példa 4 – Az első PR tanulsága

Erik az első PR-jába belerakott egy teljes feature-t – „mert az volt az első ticket". 47 fájlt érintett, 800 sor változás. A review-ra 5 napot kellett várni, 23 kommentet kapott, és az egész élmény frusztráló volt mindkét fél számára.

Frida ugyanabban a cégben az első ticketjét kettéválasztotta: az első PR-ban csak a backend logic volt, tesztekkel együtt (8 fájl, 120 sor). 24 óra alatt megkapta a review-t, 3 kisebb kommenttel, és merged. A második PR-ba kerültek a frontend változások.

Tesztfeladatok

1. kérdés
Megkaptad az első napod feladatát: „Nézd meg a projektet." Mi az első dolog, amit megnyitsz?

A) Az összes .js / .py / .php fájlt mappasorban
B) A README-t és a docs/ mappát
C) A legnépszerűbbnek tűnő fájlt (pl. index.js)
D) A git blame-et egy random fájlon

Helyes válasz: B – A dokumentáció és README adja meg a kontextust, ami nélkül a kód értelmezhetetlen.

2. kérdés
Melyik információt NEM fogod megtalálni egy projekt package.json / requirements.txt fájljában?

A) Milyen framework-öt használ a projekt
B) Van-e tesztelési keretrendszer
C) Melyik fájl a belépési pont
D) Milyen adatbázis library-t használnak

Helyes válasz: C – A belépési pontot a "main" mező tartalmazza package.json-ban (de nem mindegyiknél), vagy a Makefile / docker-compose.yml / CI konfig mutatja meg. A requirements.txt egyáltalán nem tartalmazza.

3. kérdés
Már 45 perce próbálsz megérteni egy kódrészletet, de nem haladsz. Mit tegyél?

A) Tovább próbálkozol, mert kérdezni gyengeség jele
B) Megkérdezed a seniorodat összefoglalva, mit próbáltál és hol akadtál el
C) Megkérdezed: „Nem értem ezt a kódot, magyarázd el"
D) Kihagyod és mész a következő feladatra

Helyes válasz: B – A 20 perces ökölszabályt már rég túllépted, és a strukturált kérdés (mit próbáltam, hol akadtam el) profi és hatékony.

4. kérdés
Melyik git parancs mutatja meg, melyik fájlok változtak a legtöbbet az utóbbi commitokban?

A) git log --oneline -20
B) git log --stat -10
C) git diff HEAD~10
D) git blame

Helyes válasz: B – A --stat flag mutatja, melyik fájlok hány sorral változtak commitonként. Az --oneline csak a commit üzeneteket adja röviden.

5. kérdés
Miért érdemes onboarding közben saját notes-okat vezetni?

A) Mert a cég elvárja
B) Mert megerősíti a megértést, és később referencia lehet – akár a következő júniornak is
C) Mert a code review-ra hivatkozhatsz rájuk
D) Nem érdemes, mert a kód maga a dokumentáció

Helyes válasz: B – Az onboarding notes aktív feldolgozás, referencia és tudásátadás egyszerre.

6. kérdés
Milyen méretű legyen az ideális első PR?

A) Minél nagyobb, hogy megmutasd, képes vagy komoly munkát végezni
B) Csak typo fix, mert nem akarsz hibázni
C) Kis, jól körülhatárolt változtatás – néhány fájl, néhány tucat sor, lehetőleg teszttel
D) Pontosan akkora, mint az első ticket – semmi több, semmi kevesebb

Helyes válasz: C – A kis, tiszta PR gyorsan reviewolható, pozitív visszajelzést hoz, és lehetőség a tesztek megírására is.

7. kérdés
Milyen ONBOARDING-specifikus kérdéseket MINDIG érdemes feltenni? (Jelöld meg az összeset, ami igaz.)

A) „Mi az ajánlott scope az első PR-hoz?"
B) „Milyen IDE-t kell használnom?"
C) „Van-e onboarding dokumentum?"
D) „Kire érdemes figyelni code review-nál?"
E) „Van valami, amit a README nem mond el, de kellene tudnom?"

Helyes válaszok: A, C, D, E – Az IDE kérdése (B) hasznos lehet, de nem kritikus onboarding szempontból. Az A, C, D, E kérdések azok, amelyek valóban időt spórolnak és segítik az integrációt.

8. kérdés
Melyik mappanév utal leginkább az alkalmazás üzleti logikájára (nem HTTP kezelés, nem adatbázis réteg)?

A) controllers/
B) models/
C) services/
D) utils/

Helyes válasz: C – A services/ réteg tartalmazza tipikusan az üzleti logikát. A controllers/ a HTTP kéréseket kezeli, a models/ az adatstruktúrákat, a utils/ segédfüggvényeket.

9. kérdés
Melyik állítás HELYES az ismeretlen kódbázis feltérképezéséről?

A) Először minden fájlt el kell olvasni, aztán jön a megértés
B) A fájlstruktúra vizsgálata több információt ad, mint véletlenszerű fájlolvasás
C) A git history nem releváns az onboarding szempontjából
D) Ha nincs README, a projekt értékelhetetlen

Helyes válasz: B – A mappastruktúra azonnali áttekintést ad az architektúráról és szándékokról. A git history nagyon értékes (C hamis), és egy hiányos README is fontos jel – de nem teszi a projektet értékelhetetlenné (D hamis).

10. kérdés
Mit jelent a „top-down feltérképezés, bottom-up mélyülés" elve az onboarding kontextusában?

A) Előbb az adatbázist értsd meg, aztán az API-t, végül a UI-t
B) Előbb a magas szintű struktúrát (mappaszerkezet, architektúra) értsd meg, és csak utána mélyülj az egyes fájlokba és függvényekbe
C) Előbb a dokumentációt olvasd, utána kérdezz a seniortól
D) A senior kódját értsd előbb, a junior kódját utána

Helyes válasz: B – A top-down azt jelenti: először a nagy kép (mappaszerkezet, belépési pontok, dependency graph), utána fokozatosan mélyülsz konkrét fájlokba és függvényekbe. Ez megakadályozza, hogy elvessz a részletekben kontextus nélkül.