Megjegyzések
- Kérjük, adja meg, hogy melyik nyelvet szeretné dokumentálni, a szabványok és az eszközök nyelvenként változnak .
- Kezdje ezzel: Mit kellett volna megoldania / megtennie a szoftverének? Dokumentálja a lépéseket annak elsődleges és végrehajtására.
- Keresse meg a meglévő kódot a meglévő nyílt forráskódú projektekben. Kérjük, olvassa el a meglévő kódot. Akkor hasonlítsa össze a tiéddel. Végül, miután ezt megtette, kérjen konkrét kérdéseket a megtalált kód alapján.
Válasz
Dokumentálnia kell:
- a szándékot, a miértet;
és
- amit nem legyen nyilvánvaló, a hogyan.
Miért optimalizálta ezt a bitet, mire való pontosan ez a parancsikon, milyen eredményre számít, mi a követelmény, ennek miért van oka Először is, hova küldik ezeket az adatokat, honnan veszi az inputot, ha ez többszálú, magyarázza el a modellt, ha van adatbázis, magyarázza el a sémát, a linkeket, miért …
Ne dokumentálja a nyilvánvalót. A bemutatásra sokféle módon lehet ezt megtenni. Személy szerint szeretem a beillesztett megjegyzéseket (régebbi programozó vagyok, és akkor még nem voltak divatos eszközeink – plusz én egyszerűen egyszerűnek és egyértelműnek találja). Ha valami fantáziára vágyik, győződjön meg arról, hogy az nem fogyasztja túl sok idejét, különben hamarosan el is hagyja.
Megjegyzések
- A szándék gyakran a leghasznosabb, meg tudom nézni a kódot és megérteni, hogy mit csinál, de nagyon hasznos lehet megérteni, hogy a fejlesztő miért tette így.
Válasz
Olvassa el saját kódját, amelyet 2 vagy több évvel ezelőtt írt.
Tegye fel a kérdést magának, hogy milyen típusú dolgok nem egyértelműek, és hagyja, hogy megvakargassa magát elolvasáskor. Az ilyen típusú dolgok (bármi is legyenek, a különböző programozók számára különbözőek lesznek) az, amit először el akar kezdeni dokumentálni minden új fejlesztett kóddal, vagy egy régi kóddal, amelyet újraír / újrafelhasznál. Bármilyen formázás, amely lassítja a megértését , változás.
Vagy máskülönben, 2 év múlva …
Válasz
Egy dolog, amit érdemes include a függőségek. Ha egy függvény valamire támaszkodik onnan , akkor doc Mit jelent, hol van ott és miért.
Válasz
Mivel a PHP-t használja, PHPDoc egy jó hely a kezdéshez. Az API dokumentációt beépítheti a forrásba, majd ugyanazzal a formátummal írhatja az oktatóanyagokat és a felhasználói dokumentációkat. A kimeneti formátumban is kap némi rugalmasságot.
Válasz
Mindig úgy kezdem el a kódot írni, hogy először a megjegyzéseimet írom. Írja le a program folyamatát, és rájön, hogy mit kell kommentálni, és mi nem. Miután elkezdte írni a kódot, feldíszíti azokat a részeket, amelyek további magyarázatra szorulnak, és finomítja az öndokumentáló részeket.
Miután minden osztály, funkció vagy módszer elkészült, visszalépek és megjegyzéseket fűzök hozzá egy olyan dokumentumgenerátorhoz, mint a doxygen vagy a PHPDoc. Ezzel megszerezheti a tényleges API dokumentációt.
Attól függően, hogy ki használja a kódomat, “írok egy hivatalos leírást a működési dokumentumról akár LaTeX-ben, akár Word-ben.
Válasz
A oxigén a legtöbb nyelvet lefedi. Töltenie kell egy kis időt a szintaxis megértésével, de a nagy kérdés az, hogy mit kell dokumentálni. Minden funkciót fekete dobozként kezeljen. Dokumentálja, hogy mi kerül be és mi megy ki. Dokumentálja, hogy milyen hibákat csapdázik, hogy az argok nullák lehetnek-e, visszaadhat-e nullat.
Ne feledje, hogy csak néhány hónap múlva nem fogja tudni kitalálni, hogy mi a fenét csinál egy függvény. Csak időt spórol magának.