06 óra

Fejlesztői dokumentáció készítése

A fejlesztői dokumentáció a fejlesztőknek szóló olyan írásos anyag, amelynek célja az adott szoftver további fejlesztésének, a hibakeresésnek, valamint átírásának hatékony támogatása.

A fejlesztői dokumentációk a következők lehetnek:

• Specifikációk és követelményanalízis: A dokumentáció tartalmazza a program követelményeit, korlátozásait, hatékonysági jellemzőit és alkalmazandó adatszerkezeteit.
• Futási környezet leírása: Ide tartozik a számítógép, operációs rendszer, memóriaméret, perifériák, grafikus kártya stb. leírása.
• Fejlesztői környezet leírása: A választott programnyelv(ek) és verziószáma, eljáráskönyvtárak, unitok felsorolása.
• Algoritmusok és adatok leírása: Az algoritmusok, típusok, osztályok és programkonstansok részletes ismertetése.
• Kódolási szabályok és tesztesetek: A dokumentáció tartalmazza a kódolási szabályokat, egyéni konvenciókat, valamint a program működését ellenőrző teszteseteket.
• Fejlesztési lehetőségek és készítői adatai: A dokumentum bemutatja a program készítőjét és az esetleges továbbfejlesztési lehetőségeket.

Forráskód dokumentálása

A forráskód dokumentálása rendkívül fontos a fejlesztői munka során. A megfelelő dokumentáció segít más fejlesztőknek és jövőbeli önmagadnak is megérteni a kódot, könnyebb hibakeresést, és a program hatékonyabb továbbfejlesztését teszi lehetővé.

De ha én írtam, akkor értem is a kódot!

Értem, értem! A kód néha olyan, mint egy titkos nyelv, amit csak a programozók és a jóisten értenek... Fél év múlva már csak a jóisten fogja érteni.

Még a Copilot is egyetért a fenti állítással!

"Teljesen egyetértek! A kód néha tényleg olyan, mint egy titkos nyelv, amit csak a programozók és a jóisten értenek. De ne aggódj, a jó dokumentációval még a jóisten is könnyebben megérti majd!"

A forráskód dokumentálása során az alábbi szempontokat kell figyelembe venni:

• Megjegyzések (kommentek): A kód részleteinek kommentekkel történő ellátása. Írd le, hogy miért csináltad így, milyen problémát old meg, vagy milyen döntéseket hoztál.
• Függvények és metódusok dokumentálása: Minden függvény vagy metódus elején írj egy rövid leírást arról, hogy mit csinál, milyen paramétereket vár, és milyen értéket ad vissza.
• Változók és konstansok: Ha egy változó vagy konstans neve nem magától értetődő, írd le, hogy miért van rá szükség, és milyen típusú adatot tárol.
• Használt könyvtárak és modulok: Ha a kód külső könyvtárakat vagy modulokat használ, dokumentáld hogy mire szolgálnak, és miért választottad őket.
• Tesztesetek és példák: Adj hozzá példákat a kódodhoz, hogy mások könnyebben megérthessék a működését.
• Verziószám és szerző: Ne felejtsd el dokumentálni a kód verzióját és a szerzőt.

A dokumentálás során törekedj a hatékonyság és az egyensúly megtartására!

Különösen a megjegyzések helytelen használata még ronthat is a kód minőségén és olvashatóságán. Ha a tiszta kód elveket betartjuk, akkor a dokumentálás szükségessége a minimumra csökkenthető. A dokumentálásról szóló jó tanácsokat olvasd el a projektmunka követelmények oldalon még egyszer!

Javadoc

A forráskód dokumentálása során az adott nyelv által támogatott eszközöket használhatjuk. A projektmunka Java programozási nyelven készül, így ezen a kurzuson a Javadoc használatával ismerkedünk meg. A Javadoc által használt stílust többé-kevésbé más dokumentációs eszközök is támogatják, például a C/C++ kódok dokumentálására alkalmazott Doxygen is, ezért az itt megszerzett ismeretek más környezetben is hasznosak lesznek.

A Javadoc stílusú kommentek két egységből állnak. Egy block címke (@), amely az adott komment szerepét azonosítja, valamint egy leírás, ami tulajdonképpen maga a megjegyzésünk. A kommentek elhelyezésére a forráskódban a következő szinteken van lehetőség:

• Osztályok: Az osztályszintű Javadoc az osztály szerepének rövid leírását tartalmazza kiegészítve szerzőkre és a verzióra vonatkozó információkkal (@author, @version, @since), valamint az esetleges kapcsolódó linkekkel (@link).

  /**
   * Short description about the Test class.
   * 
   * @author      Firstname Lastname <address @ example.com>
   * @version     1.6   (current version number of program)
   * @since       1.2   (the version of the package this class was first added to)
  */
  public class Test {
      // class body
  }
  

• Mezők: A mezők, illetőleg az adattagok dokumentációja többnyire egyszerű, az adott adattag szerepét írja le. Tiszta kód elvek használatával csak fontos kiegészítő információkat szoktak itt közölni (pl. mértékegység).

  Kerüljük el a többszörös mezők használatát a dokumentációban!

  Egy dokumentációs megjegyzésben kerüljük el több adattag szerepének ismertetését. Ha szükséges szedjük szét a definíciókat!

  /**
   * The horizontal and vertical distances of point (x,y)
  */
  public int x, y;      // AVOID
  

  /**
   * The horizontal distance of point.
  */
  public int x;
  
  /**
   * The vertical distance of point.
  */
  public int y;
  

• Metódusok: A metódusok dokumentálása talán a legfontosabb, hiszen a publikus metódusok azok, amelyeket biztosan használnak más fejlesztők is, ha kommunikálnak az általad készített osztállyal. Ebből adódóan több címkét is használunk a metódusok dokumentálása során:

  • @param: a metódus paramétereinek leírása
  • @return: a metódus által visszaadott objektum leírása
  • @see: hasonló, mint a @link, de kontextuson belüli hivatkozás
  • @throws: a metódus által dobott kivételek

  /**
   * Short one line description.                           (1)
   * <p>
   * Longer description. If there were any, it would be    (2)
   * here.
   * <p>
   * And even more explanations to follow in consecutive
   * paragraphs separated by HTML paragraph breaks.
   *
   * @param  variable Description text text text.          (3)
   * @return Description text text text.
   */
  public int methodName (...) {
      // method body with a return statement
  }
  

  Részletesebb leírást, valamint példákat ezen a linken találhatunk.

Forráskód dokumentálásának egyéb elemei

A forráskódon belül alkalmazott megjegyzések a dokumentáció részét képezik. A megjegyzésekre viszonylag ritkán van szükség, általában pontosításokat, vagy egy komplex algoritmus egyszerűsített leírását tartalmazzák. Erre akkor van szükség, ha az adott metódus, vagy blokk működése a forráskódból nem világos, vagy az implementált algoritmus túlságosan bonyolult.

A fentieken kívül speciális dokumentációs elemekkel is találkozunk a forráskódban. Az egyik ilyen jelölés a TBA. A TBA a To Be Announced rövidítése, olyan kiegészítő jelölés, amely azt jelzi a fejlesztőnek, hogy az érintett szakasz még további kiegészítésekre, pontosításokra szorul.

A másik gyakran alkalmazott jelölés a TODO, amelyet akkor alkalmaznak, mikor egy funkcionalitás, vagy blokk még kidolgozásra szorul. A TODO alkalmazásával azt jelöljük, hogy valamilyen programrészt még meg kell írnunk, míg a TBA annyit jelöl, hogy az érintett szakasz kiegészítésre szorul (tehát ez utóbbi esetben van már valamilyen implementáció).

Találkozhatunk még a FIXME jelöléssel is, amely azt jelzi a fejlesztőnek, hogy az adott szakaszon belül hiba, vagy hiányosság van, amit javítani kell.

Kommunikáció a csapaton belül a projektmenedzsment eszköz segítségével

A csapaton belüli kommunikáció hatékonysága kiemelt jelentőséggel bír egy projekt sikeres végrehajtásában. A hatékony kommunikáció biztosítja az üzenet minden résztvevő számára történő közös megértését, segíti a résztvevők közötti kapcsolat kialakítását és fenntartását, valamint a kívánt eredmények elérését.

Kommunikáció célja

A kommunikáció elsődleges célja az információ világos és hatékony közvetítése, hogy a küldő és a fogadó között közös megértés jöjjön létre.

A személyes szóbeli kommunikáció során nemcsak az általunk megfogalmazott közlendőnek van jelentése, hanem annak is, hogy ezt miként adjuk át, milyen tekintetet, gesztusokat, hanglejtést alkalmazunk, amelyek módosítják, esetleg teljesen meg is változtatják az üzenet eredeti, a nyelvi értelmezéséből származó jelentését.

Metakommunikáció

A metakommunikáció, egy másodlagos kommunikáció arról, hogy egy információdarabot hogyan kell értelmezni. Azon a gondolaton alapul, hogy ugyanaz az üzenet, amelyet eltérő metakommunikáció kísér, jelenthet valami teljesen mást, akár az ellenkezőjét is, lásd például az irónia esetét.

A projekten belüli kommunikáció is akkor a leghatékonyabb, ha az személyesen és szóban történik, amelyet a későbbi felhasználás érdekében jegyzőkönyveznek, vagy memót készítenek róla.

A gyakorlatban egy issue feldolgozása során gyakran hozunk meg egyéni döntéseket arra a feladatra vonatkozólag, amely a felelősségi körünkbe tartozik. Ezeket a döntéseket általában ritkán vitatjuk meg (kivéve, ha a döntés jelentősége ezt indokolja), viszont a döntésünkről és annak indokairól tájékoztatnunk kell a többi csapattagot.

A feladathoz tartozó kommunikációs tevékenységet az érintett issue megjegyzései közé kell felvenni. Az issue-k kezeléséről a harmadik gyakorlat anyagai között olvashatunk.

A feladatot érintő kommunikáció másik kiemelt felülete a GitLabon belül a merge request. A merge request nem más, mint egy kérelem, amelyben a fejlesztő indítványozza a saját fejlesztési ágában végzett változások beépítéset a célzott fejlesztési ágba. A kérelem tartalma a következő:

• A kérelemben érintett változások összefoglalása
• A változások és a kapcsolódó review-k
• Információ a CI pipelineról
• Commit lista
• Esetleges diszkussziót tartalmazó megjegyzések listája

A merge request kérelmeket a GitLab menü Code->Merge Request menüpontot kiválasztva, majd a megjelenő ablakban a NEW MERGE REQUEST nyomógombra kattintva hozhatjuk létre.

Új merge request issuból

A GitLab lehetőséget ad arra is, hogy a merge requesteket közvetlenül az issuek-ból hozzuk létre.

A dialógusban válasszuk ki a forrás és cél fejlesztési ágakat, majd kattintsunk a COMPARE BRANCHES AND CONTINUE nyomógombra. Az alábbi dialógust kapjuk.

A dialógusban adjunk meg egy címet, amellyel a kérelmünket azonosítjuk. Figyeljünk arra, hogy a merge request egy kommunikációs forma is egyben, ezért fontos, hogy a választott cím elég informatív legyen. A részleteket természetesen nem a címben, hanem a Description mezőben kell közölni. Hasonlóan, mint a commit üzenetek esetében, a leírásnak itt is tükröznie kell azt, hogy milyen elemeket érint a kérelem, mit módosítottunk rajtuk, és a módosításokat mi indokolta. A felület lehetőséget ad arra is, hogy draft formában dolgozzunk, ami biztosítja, hogy addig nem történik tényleges merge művelet, amíg nem jelezzük explicit módon, hogy végeztünk a szerkesztéssel.

A kérelemhez további adatokat is megadhatunk. Ezek közül az Assignee és a Reviewer a legfontosabb. Az Assignee azt a személyt (vagy személyeket) jelöli, aki jóváhagyja a kérelmet. Fontos, hogy a jóváhagyó rendelkezzen írási jogosultsággal azon a fejlesztési ágon, amelyet célként jelöltünk meg. Amennyiben Reviewer is kijelölésre kerül, úgy a kérelem tartalmát annak tényleges mergelése előtt ellenőrizni kell az itt megadott személynek. Az ellenőrzés megtörténtének tényét a Reviewer a kérelmen jelzi.

A kérelemhez adható meg címke és mérföldkőhöz is csatolhatjuk azt.

Kell használni a mérföldköveket minden esetben?

A mérföldkő használata a projektmunkában nem kötelező.

A kérelmen van lehetőség két opció megadására, ezeket akkor használjuk, ha a kérelem elfogadását követően az adott fejlesztési ágon már nem szeretnénk tovább dolgozni.

Miután a kérelmet kitöltöttük, kattintsunk a CREATE MERGE REQUEST nyomógombra, amelynek hatására a kérelem elkészül és a megjelölt résztvevők számára elérhetővé válik.

A jóváhagyók az aktív kérelmeket a GitLab menü Code->Merge Request menüpontot kiválasztva tekinthetik meg. A Reviewer feladata a kérelem ellenőrzése részleteiben is (Overwiev, Commits, Pipelines, Changes). Ha mindent rendben talált, akkor az APPROVE nyomógombbal jóváhagyhatja a kérelmet. A jóváhagyott kérelem esetében a jóváhagyás visszavonható a REVOKE APPROVAL nyomógombra történő kattintással.

Fontos, hogy a tényleges merge műveletet az a személy végezze el, akinek írási joga van a target branchen. A jóváhagyott és nem draft módban lévő kérelmek esetén látható a MERGE nyomógomb, amelyre kattintva a mergelés lefut.

Ha Draft módban van a kérelem, akkor az alábbihoz hasonló blokkot látunk a képernyőn.

Auto merge

Ha be van állítva a Set to auto-merge, akkor a kérelem automatikusan mergelésre kerül, ha az alábbi feltételek teljesülnek:

• A kérelem pipeline sikeresen befejeződik.
• Minden szükséges jóváhagyás rendelkezésre áll.

Amennyiben a cél fejlesztési ágon már más változások jóvá lettek hagyva, úgy merge conflict keletkezik. Ilyen esetben el kell dönteni, hogy melyik változás az, amelyiket meg kívánjuk tartani. A felületen ilyenkor lehetőség van a konfliktusok feloldására a figyelmeztető blokkon lévő RESOLVE CONFLICT nyomógombra kattintva.

A konfliktusok feloldásának a módja megegyezik azzal, amit a Git branching model esetében tanultunk.

A GitLab lehetőséget ad arra is, hogy a projektet érintő dokumentációnkat Wiki oldal formájában készítsük el. Akárcsak a GitLab egészében, a Wiki-n is használhatjuk a markdown formát. A tananyagnak nem része a GitLab Wiki használatának bemutatása, az érdeklődő hallgatók erre a linkre kattintva további információkat tudhatnak meg az eszközről és annak használatáról.