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

Ez az oldal a korábbi SCH wiki-ről lett áthozva. Az eredeti változata itt érhető el.

Ha úgy érzed, hogy bármilyen formázási vagy tartalmi probléma van vele, akkor kérlek javíts rajta egy rövid szerkesztéssel.

Ha nem tudod, hogyan indulj el, olvasd el a migrálási útmutatót

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.