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

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.