A programozás alapjai - Fejlesztői dokumentáció útmutató

A VIK Wikiből
A lap korábbi változatát látod, amilyen Szikszayl (vitalap | szerkesztései) 2014. március 13., 15:01-kor történt szerkesztése után volt.
(eltér) ← Régebbi változat | Aktuális változat (eltér) | Újabb változat→ (eltér)
Ugrás a navigációhoz Ugrás a kereséshez

Mit érdemes egy program fejlesztői dokumentációjába írni?

Alaphelyzet: képzeld el, hogy programozó vagy, aki tök ismeretlenül találkozik azzal a programmal, amit most írtál, és neked kell továbbfejleszteni/kijavítani/techsupportot nyújtani a felhasználóinak. Amire ilyenkor szükséged van, az a programozói dokumentáció. Valami, amiből egy másik programozó viszonylag rövid idő alatt át tudja eléggé látni a kódodat, hogy tudjon vele dolgozni. Konkrétan pedig:

  • Pár mondatos összefoglaló arról, hogy tulajdonképpen mit is csinál a program
    • "A program beolvas egy fájlt, a fő ciklusban megjeleníti az aktuális tartalmat, a júzer választhatja, hogy hogyan akarja módosítani, a választását egy switch-csel értékelem ki, és kilépéskor lezárom a fájlt."
  • Melyik függvény mire való, milyen paramétereket kap, mit ad vissza, mi egyebet változtat (pl. globális változók), hiba esetén mit csinál
    • "A rekord_beolvas függvény egy fájlmutatót és egy olvasási módot jelző int-et kap, a fájlból beolvas egy rekordot, a módtól függően kitörli belőle a szóközöket, és visszaadja a létrehozott rekordra mutató pointert."
  • Ha vannak globális változók, melyik mire való, melyik mikor kap kezdőértéket, hol és mikor változik vagy használódik valamire
    • "jatek_mod az aktuális játékmódot tárolja, értéke 1, ha egyjátékos, 2, ha kétjátékos módban játszik, a főmenü függvény állítja be."
  • Alkalmazott adatstruktúrák, melyik struct mire való, melyik mezője mire való
    • "struct szemely egy láncolt lista, ami egy ember nevét és születési idejét tárolja."
  • Használt algoritmusok pl. rendezés, vagy kódolás, miért éppen az az algoritmus van megírva az adott célra
    • "Az emberek adatai buborékrendezéssel rendezem név szerint, hogy ne legyen nagy a memóriahasználat."
  • Ha a program használ fájlokat, milyen fájlokkal dolgozik a program, ha saját formátumot használ, annak a formátuma
    • "BMP és JPG formátumú képeket képes olvasni, de csak BMP-t tud írni."
    • "Az adatokat egy szöveges fájlban tárolom, minden sorban egy ember adatai, sorszám-név-születési idő sorrendben, mindegyik adat ki van egészítve szóközökkel 29 karakterre."
  • A program hogyan kommunikál a felhasználóval
    • "A programnak parancssorban lehet átadni a megnyitandó fájl nevét."
    • "Futás közben szöveges képernyőn megjelenített menükkel lehet vezérelni."
  • A futás közben előforduló hibák, a program hogyan reagál rájuk
    • "Ha nem sikerül a fájl megnyitása, a program azonnal kilép (-1)-es kóddal."
    • "Ha a memóriafoglalás nem sikerül, helyette egy ideiglenes fájlban tárolja az adatokat."
  • A program korlátai
    • "Csak Dev-C++ 4.0 vagy későbbi alatt fordul le."
    • "Futtatni csak Intel x86-os processzorokon lehet."
    • "Megnyitni csak 4 GB-nál kisebb fájlokat tud."
    • "1 MB-nál nagyobb adatsorokra a rendezés nagyon lassú."
  • A programban maradt tökéletlenségek, hibák
    • "Ha a felhasználó szám helyett betűt ír be, akkor a program kifagyhat."

Ezeken kívül bármi egyébről lehet írni, ami a program megírása vagy használata szempontjából fontos. Akinek eszébe jut valami, amit kihagytam, írja be ide is.

-- G - 2007.12.11.