Forráskód megjegyzés Styling tippek és legjobb gyakorlatok
A nagy projektekre fordított fejlesztők megértik a kódmegjegyzések fontosságát. Amikor sok funkciót építesz be ugyanarra az alkalmazásra, a dolgok általában bonyolultak. Olyan sok adat bit van, amely függvényeket, változó referenciákat, visszatérési értékeket, paramétereket ... hogyan számíthatsz tovább?
Nem meglepő, hogy a kódok kommentálása alapvető fontosságú mind egyéni, mind csapatmunka projektekben. De sok fejlesztő nem tudja, hogyan kell ezt a folyamatot megtenni. Néhány saját trükköt felvázoltam tiszta, formázott kódmegjegyzések létrehozása. A szabványok és a megjegyzéssablonok a fejlesztők között változhatnak, de végül is törekedni kell tiszta és olvasható megjegyzések tovább magyarázza a kódod zavaró területeit.
Meg kell kezdenünk néhány véleménykülönbség megvitatását. Ez jobb ötletet ad Önnek arról, hogy mennyire részletes lehet a projektkóddal. Ezután néhány konkrét tippet és példát kínálok, amelyeket azonnal elkezdhetünk használni!
Kommentárstílusok: áttekintés
Meg kell jegyezni, hogy ezek az ötletek csupán iránymutatások tisztább észrevételek felé. Az egyes programozási nyelvek nem tartalmaznak iránymutatásokat vagy előírásokat a dokumentáció beállításához.
Ezzel együtt a modern fejlesztők csoportosították, hogy formázzák saját kódmegjegyzési rendszerüket. Néhány mainstream stílust kínálok, és részletezem a céljukat.
Inline megjegyzések
Gyakorlatilag minden programozási nyelv kínál inline megjegyzések. Ezek csak egysoros tartalomra korlátozódnak, és csak egy bizonyos pont után kommentálják a szöveget. Tehát például a C / C ++-ban egy ilyen inline megjegyzést kezd el:
// a var myvar = 1 változók listájának megkezdése ...
Ez tökéletes ahhoz, hogy néhány másodpercre beilleszkedjen a kódba megmagyarázza a zavaró funkciókat. Ha sok paraméterrel vagy függvényhívással dolgozik, akkor a közelben megfordíthatja az inline megjegyzéseket. De a leghasznosabb felhasználás a a kis funkcionalitás egyszerű gondolkodása.
if (callAjax ($ params)) // sikeresen futtatja a callAjax-ot a felhasználói paraméterekkel ...
A figyelmeztetésnek mindenekelőtt a kódnak új sorban kell lennie a nyitó konzol után. Ellenkező esetben mindannyian ugyanabba a megjegyzési sorba kerülne! Kerülje el a fedélzetet mivel általában nem kell az egysoros megjegyzéseket látni az oldal egészében, de különösen azért, mert a kódban lévő összeköttetések zavaróak, ezeket sokkal könnyebben le lehet vetni az utolsó pillanatban.
Leíró blokkok
Ha nagy magyarázatot kell tartalmaznia, általában egyetlen vonalhajózás nem teszi meg a trükköt. A programozás minden területén előzetesen formázott megjegyzési sablonok használhatók. Leíró blokkok leginkább a funkciók és a könyvtárfájlok köré tekinthetők. Amikor új funkciót állít be, jó gyakorlat adjunk egy leíró blokkot a nyilatkozat felett.
/ ** * @desc megnyit egy modális ablakot egy üzenet megjelenítéséhez * @param string $ msg - a megjelenítendő üzenet * @return bool - siker vagy hiba * / funkció modalPopup ($ msg) …
A fentiek egy egyszerű példa egy leíró funkció kommentárra. Valószínűleg írtam egy függvényt a JavaScript-ben modalPopup amely egyetlen paramétert vesz igénybe. A fenti megjegyzésekben a phpDocumentorhoz hasonló szintaxist használtam, ahol minden sor előtt a @ szimbólumot, amelyet egy kiválasztott gomb követ. Ezek semmilyen módon nem befolyásolják a kódodat, így írhatsz @leírás ahelyett @desc változások nélkül.
Ezeket a kis kulcsokat ténylegesen hívják megjegyzések címkék amelyek a honlapon erősen dokumentáltak. Nyugodtan töltse ki a sajátját, és használja ezeket a kódja alatt. Úgy találom, segítenek abban, hogy mindent megtartsanak Egy pillantásra megnézhetem a fontos információkat. Azt is észre kell vennem, hogy ezt használtam / * * / blokk-stílusú kommentálási formátum. Ez mindent megtart sokkal tisztább mint az egyes soroknál kezdődő kettős sáv hozzáadása.
Csoport / osztály megjegyzések
A funkciók és a hurkok kommentálásán kívül a blokkterületeket nem használják olyan gyakran. Hol van szüksége erősre blokkolja a megjegyzéseket a háttérdokumentumok vagy a könyvtárfájlok fejében vannak. A webhely minden fájlja számára könnyű, hogy mindenre kiterjedjen és szilárd dokumentációt írjon - ezt a gyakorlatot sok olyan CMS-ben láthatjuk, mint a WordPress.
Az oldalának legmagasabb területe magában foglalja a fájlra vonatkozó megjegyzéseket. Így lehet gyorsan ellenőrizze, hol szerkeszti ha egyszerre több oldalon dolgozik. Ezen kívül ezt a területet is használhatja egy adatbázis a legfontosabb funkciókhoz, amelyekre szüksége lesz az osztályból.
/ ** * @desc ebben az osztályban a felhasználói interakció függvényei * a példák közé tartozik a user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / absztrakt osztály myWebClass
Láthatjuk, hogy csak egy kis mintaosztályt használtam a hamisításhoz myWebClass kód. Néhány meta információt adtam hozzá a nevem és az e-mail címem. Amikor a fejlesztők nyílt forráskódot írnak, ez általában jó gyakorlat, így mások segítséget kérhetnek. Ez egy nagyobb módszer a nagyobb fejlesztési csoportokban való munkában.
A címke @kívánt nem olyasvalami, amit máshol használtam. Néhány projektemben tartottam a formátumot, csak azokon az oldalakon, ahol sok módszert alkalmaztam. Ha olyan fájlba helyezi az oldalakat, amelyeket el kell érnie, mielőtt bármilyen kódot kiadna. Így ezeknek a részleteknek a hozzáadását a főosztály megjegyzésblokkja jó módja ne feledje, mely fájlok szükségesek.
Elülső kód megjegyzése
Most, hogy 3 fontos megjegyzési sablont fedeztünk fel, nézzük meg néhány más példát. Sok frontend fejlesztő van, akik a statikus HTML-ről a jQuery és a CSS kódra költöztek. A HTML-megjegyzések nem annyira célirányosak, mint a programozási alkalmazások, de amikor stíluskönyvtárakat és oldalszkripteket írunk, a dolgok idővel zavarosak lehetnek.
A JavaScript egy hagyományosabb módszert követ, mint a Java, PHP és C / C++. A CSS csak a sáv és a csillag által definiált blokk-stílusú megjegyzéseket használja. Ne feledje, hogy a megjegyzések nyíltan jelennek meg a látogatóknak, mivel sem a CSS, sem a JS nem értelmezi a szerver oldalt, de ezek közül bármelyik jól működik, ha informatív tidbiteket hagy a kódjában, hogy visszatérjen.
A CSS-fájlok kifejezetten felbontása házimunkát jelenthet. Mindannyian ismerjük, hogy egy inline megjegyzést hagyunk, hogy megmagyarázzuk az Internet Explorer vagy a Safari javítását. De úgy gondolom, hogy a CSS kommentálása a jQuery és a PHP szinteken használható. Mielőtt néhány részletes tippet adnánk a kód kommentálásához, vigyázzunk a stíluscsoportok létrehozására.
CSS stíluscsoportok
Azok számára, akik évek óta tervezték a CSS-t, szinte második természetű. Lassan feljegyezed a stíluslapok összes tulajdonságát, szintaxisát és saját rendszerét. Saját munkám révén létrehoztam, amit hívok csoportosítás hasonló CSS-blokkokat egy területre párosítani.
Amikor visszajön a CSS szerkesztéséhez, néhány másodperc alatt könnyen megtalálom, amire szükségem van. A stílusok csoportosításának módja teljesen rajtad múlik, és ez a rendszer szépsége. Van néhány előre beállított szabványom, amelyeket az alábbiakban ismertetem:
- @resets - az alapértelmezett böngésző margók, padding, fontok, színek stb.
- @fonts - bekezdések, címek, blokkjegyek, hivatkozások, kód
- @navigation - a fő webhely navigációs linkje
- @layout - csomagolás, konténer, oldalsó sávok
- @header & @footer - ezek változhatnak a designtól függően. A lehetséges stílusok közé tartoznak a linkek és a rendezetlen listák, a láblécoszlopok, a fejlécek, az al-navok
A stíluslapok csoportosításakor megtaláltam a címkézési rendszer sokat segíthet. Azonban a PHP-vel vagy a JavaScript-szel ellentétben egyetlen nevet használok @csoport címke, amelyet egy kategória vagy kulcsszó követ. Az alábbiakban 2 példát is mellékeltem, hogy érzem magam, amit értem.
/ ** @group lábléc * / #footer stílusok…
/ ** @group lábléc, kis betűtípusok, oszlopok, külső linkek ** /
Alternatív módon hozzáadhat egy kis extra részletet minden megjegyzésblokkhoz. Én választom egyszerű és egyszerű dolgokat tartani így a stíluslapok könnyen leolvashatók. A kommentálás a dokumentációról szól, mindaddig, amíg megérti az írást, hogy jó menni!
4 tipp a jobb kommentáláshoz
A cikk első felét a kód kommentálásának különböző formátumait töltöttük. Beszéljünk meg néhány általános tanácsot a kód tisztaságáról, szervezéséről és könnyen érthetővé tételéről.
1. Tartsa mindent olvashatónak
Néha fejlesztőként ezt elfelejtjük az embereknek megjegyzéseket írunk az olvasásra. Az összes programozási nyelv, amit megértünk, a gépekre épül, így unalmas lehet a szöveges szövegre konvertálni. Fontos megjegyezni, hogy nem vagyunk itt, hogy főiskolai szintű tanulmányt írjunk, hanem csak elhagyja a tippeket!
függvény getTheMail () // code here építeni fog e-mail / * futási kódot, ha az egyedi sendMyMail () függvényhívásunk visszaadja az igazi FindMyMail () -t a /libs/mailer.class.php fájlban, akkor ellenőrzi, hogy a felhasználó kitölt-e minden mezőt és az üzenet elküldve! * / if (sendMyMail ()) vissza igaz; // tartsa tisztán és megjelenítse a képernyőn megjelenő sikert
Még csak néhány szó is van jobb mint a semmi. Amikor visszajön a szerkesztéshez és a projektek munkájához a jövőben, gyakran meglepő, hogy mennyit fog elfelejteni. Mivel minden nap nem ugyanazokat a változókat és funkcióneveket nézed, akkor lassan elfelejted a kódod nagy részét. Így lehet soha ne hagyjon túl sok megjegyzést! De túl sok rossz megjegyzést hagyhatsz.
Általános szabályként a hüvelykujj, egy kis időt vesz igénybe, hogy szüneteltesse és tükrözze az írás előtt. Kérdezd meg magadtól mi a leginkább zavaró a programban és hogyan lehet a legjobban magyarázni “színlelt” nyelv? Fontolja meg miért írod a kódot pontosan úgy, ahogy te vagy.
Néhány leginkább zavaró hiba jelenik meg, amikor elfelejtette az egyénre szabott (vagy harmadik fél) funkcióinak célját. Hagyj egy megjegyzési nyomvonalat, ami visszaáll néhány más fájlra ha ez segít könnyebben emlékezni a funkcionalitásra.
2. Csökkentse néhány helyet!
Nem tudom eléggé hangsúlyozni, hogy mennyire fontos fehér űr lehet. Ez megy kétszer igaz a PHP és a Ruby fejlesztők számára, akik több száz fájlt tartalmazó masszív weboldalakon dolgoznak. Egész nap bámulsz a kódra! Nem lenne nagyszerű, ha csak át tudná vinni a fontos területeket?
$ dir1 = "/ home /"; // a fő home könyvtár beállítása $ myCurrentDir = getCurDirr (); // állítsa be az aktuális felhasználói könyvtárat $ userVar = $ get_username (); // aktuális felhasználó felhasználóneve
A fenti példában megemlítjük, hogy az egyes sorokhoz a megjegyzés és a kód között elhelyezett extra párnázás történik. Ahogy görgetsz a fájlok között, ez a kommentálási stílus egyértelműen kiemelkedik. Azt megkönnyíti a hibákat és több százszor kijavítja a kódját ha változó blokkok vannak tiszta.
Hasonló feladatot végezhet a kódon belül egy függvényen belül, ahol zavarodott, hogy hogyan működik, de ez a módszer végül zavarodná a kódot inline megjegyzésekkel, és ez a pontos ellentét a rendezett! Ebben a forgatókönyvben ajánlom nagy logó-megjegyzés hozzáadása a logika területéhez.
$ (dokumentum) .ready (funkció () $ ('. sub'). hide (); // elrejtése al-navigáció a pageload / ** -on egy kattintási esemény ellenőrzése egy. akció, így az oldal nem változik a kattintáson keresztül, hozzáférjen a .itm szülő eleméhez, majd a következő .sub listához, hogy a ** / $ ('. itm a') nyitását / zárását kapcsolja. ) e.preventDefault (); $ (ez) .parent (). következő ('. sub'). slideToggle ('fast'););); Ez egy kis jQuery kód, amely egy almenü csúszó navigációját célozza meg. Az első megjegyzés azzal magyarázható, hogy miért rejtjük el az egészet .alatti osztályok. Az élő kattintások eseménykezelője felett egy blokkmegjegyzést és az összes írás ugyanabba a pontba került. Ez sokkal inkább a dolgokat teszi, mint a futó bekezdések - különösen mások számára, akik olvassák a megjegyzéseket.
3. Megjegyzés a kódolás közben
A megfelelő távolságokkal együtt ez az egyik legjobb szokás lehet. Senki sem akar visszatérni a programja után, miután munkáját és minden darabját dokumentálta. A legtöbben még csak nem is akarnak visszatérni és dokumentálni a zavaró területeket! Ez tényleg sok munkát igényel.
De ha a kódolás közben írhatja a megjegyzéseket mindent még mindig friss lesz az elmédben. Jellemzően a fejlesztők megragadnak egy problémát, és a legegyszerűbb megoldást az interneten kipirítják. Amikor megérkezik az Eureka pillanatra, és megoldja az ilyen problémát, általában egy pillanatnyi tisztaság érhető el, ahol megérti a korábbi hibákat. Ez lenne az legjobb idő nyílt és becsületes megjegyzéseket hagyhat a kódodról.
Ezenkívül gyakorlatot ad, hogy megszokja az összes fájl kommentálását. Az idő, amire szükség van ahhoz, hogy visszamegyünk, és kitaláljuk, hogyan működik valami sokkal nagyobb, miután már építetted a funkciót. Mind a jövő, mind a csapattársaink megköszönik, hogy előzetesen megjegyzéseket tettek.
4. Buggy hibák kezelése
Nem tudunk mindenki ülni a számítógép előtt órákban író kódot. Azt hiszem, megpróbálhatjuk, de valamikor aludnunk kell! Valószínűleg részt kell vennie annak a napnak a kódjával, ahol néhány nap még mindig törött. Ebben a forgatókönyvben döntő fontosságú, hogy Ön hagyjon hosszú, részletes megjegyzéseket arról, hogy hol hagyta el a dolgokat.
Még egy friss éjszakai alvás után is meglepődhet, hogy milyen nehéz lehet visszamenni a kódolás swingébe. Például, ha képfeltöltő oldalt épít, és befejezetlennek kell hagynia, akkor meg kell kommentálnia, hogy hová ment el a folyamatból. A képek feltöltése és tárolása a memóriában van? Vagy talán nem is ismerik fel a feltöltési formában, vagy talán nem jelennek meg megfelelően a feltöltés után az oldalon.
A hibák észrevétele két fő ok miatt fontos. Először is könnyedén vegye fel, ahol elhagyta és próbálkozzon újra az újdonsággal a probléma megoldásához. És másodszor is megkülönböztetni a webhelye élő gyártási változatát és a tesztelési területeket. Ne feledje, hogy megjegyzéseket kell használni magyarázza el, miért csinál valamit, nem pontosan mit csinál.
Következtetés
A webes alkalmazások és szoftverek fejlesztése egy teljesítő gyakorlat, bár nehéz. Ha Ön az egyik kevés olyan fejlesztő, aki valóban megérti az építési szoftvert, akkor fontos, hogy a kódolási képességekkel érjen. A leíró megjegyzések elhagyása csak jó gyakorlat hosszú távon, és valószínűleg soha nem fogod megbánni!
Ha javaslata van a pontosabb kódmegjegyzésekhez, kérjük, ossza meg velünk az alábbi vitaterületet!
