Kommentálva kód és dokumentáció generáció php, blog
Szállás lehetőségek dokumentáció
Nézzük meg a dokumentációt kívül a kódot. Bár ez nem az a célja ennek a cikknek. A nyílt forráskódú projektek nem ritka gyakorlat dokumentációs cikkek tárolhatók ugyanabban adattár, mint a mag kódot. Például a könyvtárban, hogy létrehoz egy hamis internetes szerelvények PHP dokumentáció helyezni a README file; olvasni, hogy a végén, akkor kell egy kis poskrolit. Népszerű HTTP-kliens PHP zabál üzletek a használati utasítás különböző fájlokat egy külön mappába docs. Store dokumentáció a következő kódot - ez minden bizonnyal szép és kényelmes. A letöltött csomag szállítója, akkor mind a kód és dokumentáció. Ha a könyvtár kicsi, ha az stabil, és nem jár a jövőben API állandó változások járnak állandó újraírás dokumentumokat, akkor nyugodtan a dokumentumok az adattár a projekt.
Kihagyja a végrehajtása a felület, csak hozzon létre egy új objektumot osztály Rabbit:
Nyúl - főnév, futtassa - az ige, méterben - a tekintetben, hogy mi vagyunk hozzá módszerrel továbbítja a lényege. Ezzel a rendszer, akkor írj módszerek
De ez már túl sok:
Vannak azonban kivételek a hossza a nevét módszereket. Például, ha írsz egy spec a phpSpec. akkor nem korlátozhatja magát a hossza módszer, a lényeg, hogy átadta a lényeg. Itt egy példa a kódot, kivenni a dokumentáció phpSpec:
SPECA az eljárás nevét használja aláhúzás felvételt. így könnyebb elkapni a szem a szavakon túl, és olvasni egy hosszú mondat. Ez nem szabványos PSR ahol teveEsetnek használni. de az olvashatóság teszteket, mint az opció ideális.
A arányérzék a módszer neve is jön az idő, a tapasztalat. Akkor peep, ahogy azt a népszerű keretek és könyvtárak.
jelentéktelenség
redundancia
megbízhatatlanság
feltalálói
Nem ismert, hogy mikor és nyilvánvaló kifejezéseket kódolásához használt egy adott helyen.
Írni, de kell, hogy felelősséget vállal. Itt olyan idők, amikor szükség van rájuk.
információtartalma
Ugyanez a probléma a programozási nyelv is megoldható sokféleképpen. A programozó saját stílusát programozás és ismerkedés a kódot egy másik programozó egy másik stílus, nehéz lehet elolvasni a kódot „átlósan”. Ha bármilyen speciális programozási stílus, vagy tapasztalatból tudják, hogy az algoritmusok használata, nehéz olvasni a többi, akkor hagyja nyomokat a kódot közvetlenül kezdete előtt egy komplex kódrészletet.
figyelmeztetések
Nem dokumentálja rossz kód - változtattak rajta.
Dokumentálása segítségével dokblokov
Dokblokom lehet egy sorban, egészen addig, amíg kezdődik / **.
Dokbloki annyira hozzászokott kommyuniti PHP-programozó, amely felkészíti a PSR-5 ezek alapján (PHP szabvány ajánlás). Abban az időben az írás, még mindig tervezet formájában.
A PHP-n keresztül dokblokov dokumentálni tudja a következő elemeket tartalmazza:
Fontos az is, hogy az egyik dokblok lehet alkalmazni, hogy csak az egyik szerkezeti elem. Ie Minden funkció - a dokblok, változó egy függvényen belül - az övé, az osztály - a.
A phpdoc sok tag, de nem minden tag alkalmazható minden szerkezeti elemek. Az alábbi lista a meglévő címkéket, a felhasználási területet és magyarázat.
Elavult címkék, valószínűleg nem fogja támogatni a jövőben:
- @category (fájl, osztály) - használt csoport csomagok együtt.
- @subpackage (fájl, osztály) - van izolálására használt egyes csoportok a csomagokat.
Nem minden tag egyformán népszerű, a leggyakrabban használt: @var, @param, @return, @todo, @throws. mások - kevésbé. És mint a @property és @method én általában nem találkozott az alkalmazást, mert „munka mágikus” PHP - veszélyes :)
Könnyű használat dokblokov az IDE
Ha a fejlődő nyílt forráskódú projekt, akkor természetesen dokumentált nyilvános API segítségével dokblokov szükséges. Ez nem csak lehetővé teszi, hogy létrehoz egy kész dokumentációt, hanem lehetővé teszi, hogy a kódot kényelmes más fejlesztők saját IDE. Ami a saját kódját, hogy kiszervezik a projekt, a használata dokblokov nem tűnik nagyon megfelelő, de tájékoztassa őket használni, hogy felgyorsítja a fejlesztés.
Például, hogy a legnépszerűbb IDE PHP - PhpStorm. Tekintsük a korábbi példában nyulak Keresés:
Ez tárolja a változó $ nyúl- és $ nyúl. PhpStorm róla semmit nem tud. PHP - gyengén típusos nyelv, milyen típusú függvény eredménye nincs definiálva szigorúan annak leírása (helló PHP7, ahol ez lesz végre). Ezért az IDE kell kérni a dokblokov, hogyan kell viselkedni egy bizonyos kódot. Számos módja van. Ezt megteheti:
@return vagy adjunk hozzá egy címkét egy módszer findRabbitsInLocations:
Felhívjuk figyelmét, hogy az általunk megjelölt Nyúl []. ehelyett Nyúl. A zárójelben világossá teszik, hogy adja vissza egy tömbben tárgyak osztálya Nyúl. ha eltávolítjuk a szögletes zárójelek, az azt jelenti, hogy a módszer visszaadja egy példány a Nyúl. Mégis lehet írni, így @return null | Nyúl []. függőleges bot „VAGY”, ebben az esetben azt adja meg, hogy az eljárás adja vissza egy tömbben vagy nyúl, vagy null.
Nem számít, milyen módszerrel meghatározva a típust választja, PhpStorm mostantól ad hasznos tippeket, ha beír $ amelyeket nyulak> és várjon egy pillanatra:
Ez azért történik, mert PhpStorm tudja, hogy a változó $ nyulak vissza egy tömbben tárgyak osztálya Nyúl. Továbbá, a foreach ciklus változó $ nyúl kap az egyik eleme a tömb, amely egy-egy példánya Nyúl és PhpStorm megmutatja a nyilvánosság számára hozzáférhetővé módszerek ebben az osztályban.
Így nem nézett fel a billentyűzetet, akkor az osztályok nyilvános módszereket írtak a kollégák. PhpStorm kapsz egy nyom, és ha a módszer neve egyértelmű, akkor tudja használni elolvasása nélkül is a forráskód és dokumentáció.
Egy másik hasznos funkció dokblokov párosítva PhpStorm - figyelmeztet mintegy rossz bemeneti paramétereket. Töltsük dokblok az egyik módszer a Rabbit:
Itt jelezzük, hogy a bemeneti kell jönnie integer (megint PHP7 lehetséges lesz beállítani a szintet a nyelvi szintaxis). Mi történik, ha átadjuk ezt a módszert egy tömb?
PhpStorm szín és kapsz egy utalás arra, hogy a bemeneti várhatóan int. és továbbítja tömbben. Kényelmes, nem? Ugyanez tippeket kerül ki, és az ellentmondást az osztályok, interfészek. Ha a módszer támogatja több típusú bejövő érvek szét őket, és a |. Ebben a példában, ha runInMetres () metódus is képes feldolgozni tömbök, akkor felveheti dokblok «@param int | array $ méterre mérők» PhpStorm és megáll káromkodás.
A lehető legkevesebb kellemetlenség meg kell, hogy minden csapattag, hogy tartalmazza PhpStorm ellenőrzés dokblokov Beállítások> Szerkesztő> Vizsgálatok> phpdoc és megjegyezte, hogy minden kullancs:
Tehát érdemes használni PHP CodeSniffer (phpcs) megfelelő kódját stílus. Nem biztos, hogy mi van a kód a stílus, hanem a Symfony dokbloki kötelező. Ezért phpcs a Storm fog kiadni egy figyelmeztető menet közben. A beállításokat ugyanazon a helyen, de még mindig van egy újabb utasítást.
Természetesen ez nem teszi mindenki 100% betartani a szabályokat. De különösen félék lehet terhelni még egy idézet a könyvből: „Clean Code” azonban már nem kezeli a formázás kódot, de a jelentése ugyanaz:
„A szabályok szerint kell eljárni minden tagja a csoportnak. Ez azt jelenti, hogy minden egyes tagja a csoportnak ésszerűnek kell lennie ahhoz, hogy felismerje, nem számít, hogy hogyan kerül a nadrágtartó, ha egyhangúlag elhelyezni őket ugyanúgy. "
Generálása dokumentáció segítségével phpDocumentor
Most, hogy minden tartsák be a szabályokat, és a kód fedi dokblokami generálhat dokumentációt. Hogy az összes dokumentáció phpDocumentor nem, csak a minimális parancsok nyugszik a hivatalos honlapján.
Tehát, ha kell telepíteni phpDocumentor. Lehet belőle világszerte, mint ez:
Vagy hozzáadás függőség composer.json a projekt.
És most, hogy a könyvtárban a projekt, hogy már lefedett dokblokami, csak futtatni a konzolon:
Mint már említettem, ez a minimum tevékenységek sorozata generál dokumentációt, az opció -d src / jelzi az utat, hogy a kívánt fájlokat feldolgozni. A létrehozott dokumentációt hoz létre a kimeneti mappát. Persze, ez a segédprogram különböző paramétereket, és különböző dolgokat tudja. A megjelenés generált dokumentációt így lesz. akkor válasszon ki egy meglévő sablon vagy létrehozhat saját.
Generálása dokumentáció segítségével Sami
Egy másik eszköz létrehozására php alapú dokumentáció dokblokov - Sami segédprogramot. Talán nem annyira ismert, de úgy döntöttem, hogy megemlítem, mert a segítségével Sami dokumentáció által generált szeretett Symfony. És ő írta ezt a segédprogramot Fabien Potencier, és írt róla egyszer blogjában.
Sami dokumentáció generátor eltér phpDocumentor, hogy a konfiguráció van tárolva a PHP-fájlokat. Általában fen Sami magad is sokkal meredekebb, mint phpDocumentor, de azt kell, hogy kezeli, azaz írni egy kódot. Van még lehetőség, hogy újra a különböző kódrészletek, amelyek felelősek generáló dokumentációt. És TWIG'e Sablon kényelmes működtetéshez. Több megismerkedhetnek a Sami az oldalon a tároló GitHubról.