Zdrojový kód Komentár Styling tipy a osvedčené postupy

Vývojári, ktorí strávili nejaký čas na veľkých projektoch, chápu dôležitosť komentárov kódu. Keď vytvárate mnoho funkcií do tej istej aplikácie, veci sa zvyčajne komplikujú. Existuje toľko dátových bitov vrátane funkcií, premenných referencií, návratových hodnôt, parametrov ... ako sa očakáva, že budete držať krok?

Nemalo by byť prekvapením, že komentovanie vášho kódu je nevyhnutné, a to ako sólo, tak tímové projekty. Mnohí vývojári však nevedia, ako postupovať. Som načrtol niektoré z mojich osobných trikov vytváranie čistých formátovaných komentárov kódu. Štandardy a šablóny komentárov sa budú líšiť medzi vývojármi - ale v konečnom dôsledku by ste sa mali snažiť smerovať čisté a čitateľné pripomienky aby ste ďalej vysvetlili mätúce oblasti v kóde.

Mali by sme začať diskutovať o niektorých rozdieloch vo formátovaní komentárov. To vám prinesie lepšiu predstavu o tom, ako detailne sa môžete stať s projektovým kódom. Potom vám ponúknem niekoľko konkrétnych tipov a príkladov, ktoré môžete okamžite začať používať!

Štýly komentára: Prehľad

Treba poznamenať, že tieto prezentované myšlienky sú len pokyny k čistejším komentárom. Jednotlivé programovacie jazyky neobsahujú pokyny alebo špecifikácie pre nastavenie vašej dokumentácie.

Na základe toho sa moderné vývojári zhromaždili a vytvorili vlastný systém kódovania komentárov. Ponúkam niekoľko bežných štýlov a podrobne uvediem ich účel.

Inline komentáre

Prakticky každý programovací jazyk ponúka inline komentáre. Tieto sú obmedzené na jednoriadkový obsah a po určitom bode iba komentovať text. Takže napríklad v C / C + + začnete inline komentár takto:

// začať premenný zoznam var myvar = 1; ... 

To je ideálne pre spúšťanie do kódu na niekoľko sekúnd vysvetliť pravdepodobne mätúce funkcie. Ak pracujete s mnohými parametrami alebo funkčnými volaniami, môžete umiestniť v okolí niekoľko komentárov. Ale najvýhodnejšie použitie je a jednoduché myslenie vysvetlenie pre malé funkcie.

if (callAjax ($ params)) // úspešne spustiť callAjax s parametrami užívateľa ... code

Všimnite si, že predovšetkým kód by musel byť po novom riadku po otvorení. V opačnom prípade by sa to všetko týkalo tej istej poznámky! Nepoužívajte cez palubu pretože vo všeobecnosti nepotrebujete vidieť komentáre s jedinou líniou celú cestu po vašej stránke, ale hlavne kvôli zmäteniu križovatky vo vašom kóde, je to oveľa jednoduchšie klesať v poslednej chvíli.

Popisné bloky

Keď potrebujete zahrnúť veľké vysvetlenie, spravidla jedna podložka nebude robiť trik. K dispozícii sú predformátované šablóny komentárov, ktoré sa používajú v každej oblasti programovania. Popisné bloky sú najvýraznejšie viditeľné okolo funkcií a súborov knižnice. Kedykoľvek nastavíte novú funkciu, je to správna prax pridajte popisný blok nad deklaráciou.

/ ** * @desc otvorí modálne okno na zobrazenie správy * @param string $ msg - správa sa zobrazí * @return bool - úspech alebo chyba * / funkcia modalPopup ($ msg) ... 

Vyššie je jednoduchý príklad popisu popisnej funkcie. Napísal som pravdepodobne funkciu v JavaScripte modalPopup ktorý má jeden parameter. Vo vyššie uvedených komentároch som použil syntax podobný phpDocumentor, kde každému riadku predchádza a @ symbol, po ktorom nasleduje vybrané tlačidlo. Tieto zmeny nebudú mať žiadny vplyv na váš kód, takže by ste mohli napísať @description namiesto @desc bez akýchkoľvek zmien.

Tieto malé kľúče sú skutočne volané tagy komentárov ktoré sú na webových stránkach značne zdokumentované. Nebojte sa vytvoriť svoje vlastné a používať ich podľa svojho želania vo vašom kóde. Zistil som, že pomáhajú udržiavať všetko, čo preteká Môžem skontrolovať dôležité informácie na prvý pohľad. Mali by ste si tiež všimnúť, že som použil / * * / blokový formát komentovania. Toto bude mať všetko oveľa čistejšie než pridanie dvojitého lomítka začínajúceho na každom riadku.

Poznámky k skupine / triede

Okrem komentovania funkcií a slučiek sa oblasti blokov nepoužívajú tak často. Kde naozaj potrebujete silné blokovať komentáre sú na čele vašich backendových dokumentov alebo súborov knižnice. Je ľahké ísť von a napísať solídnu dokumentáciu pre každý súbor na vašich webových stránkach - môžeme vidieť túto prax v mnohých CMS, ako napríklad WordPress.

Veľmi horná oblasť vašej stránky by mala obsahovať pripomienky týkajúce sa samotného súboru. Týmto spôsobom môžete skontrolovať, kde upravujete pri práci na viacerých stránkach súčasne. Okrem toho túto oblasť môžete použiť ako databáza najdôležitejších funkcií, ktoré budete potrebovať mimo triedy.

/ ** * @desc Táto trieda bude mať funkcie pre interakciu používateľa * príklady zahŕňajú user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @ požadované settings.php * / abstraktná trieda myWebClass  

Môžete vidieť, že som použil malú vzorovú triedu pre falošný myWebClass code. Pridal som niekoľko meta informácií s mojím menom a e-mailovou adresou pre kontakt. Keď vývojári píšu open source kód, je to všeobecne dobrá prax, takže ostatní vás môžu kontaktovať na podporu. To je tiež pevná metóda pri práci vo väčších vývojových tímoch.

Značka @požadovaný nie je niečo, čo som videl, používa sa inde. Dostal som sa s formátom v niekoľkých mojich projektoch, len na stránkach, kde som prispôsobil veľa metód. Kedykoľvek zahrniete stránky do súboru, musia prísť pred vydaním ľubovoľného kódu. Takže pridávanie týchto detailov do bloku komentárov hlavnej triedy je dobrý spôsob pamätajte, ktoré súbory sú potrebné.

Front-end kód komentuje

Teraz, keď sme pokryli 3 dôležité šablóny komentárov, pozrime sa na niekoľko ďalších príkladov. Existuje veľa vývojárov frontend, ktorí sa presťahovali zo statického HTML do kódu jQuery a CSS. Poznámky vo formáte HTML nie sú v porovnaní s programovými aplikáciami také účelné, ale keď píšete štýlové knižnice a skripty stránky, veci sa môžu časom rozptýliť.

JavaScript používa tradičnejšiu metódu pripomienkovania podobnej Java, PHP a C / C++. CSS používa iba poznámky v štýle bloku vymedzené lomkou a hviezdičkou. Mali by ste mať na pamäti, že vaše komentáre sa otvorene zobrazia vašim návštevníkom, pretože ani CSS, ani JS nie sú analyzované na strane servera, ale niektorá z týchto metód funguje skvele, ak necháte informačné tidbits vo vašom kóde, aby ste sa vrátili späť.

Konkrétne rozbitie súborov CSS môže byť prácou. Všetci sme oboznámení s tým, že opustili inline komentár s cieľom vysvetliť opravu pre program Internet Explorer alebo Safari. Ale verím, že CSS komentáre môžu byť použité na úrovni jQuery a PHP ich používať. Nechajte sa ponoriť do vytvárania skupín štýlov predtým, než sa dotknete niektorých podrobných tipov pre komentovanie kódu.

Skupiny štýlov CSS

Pre tých, ktorí dlhé roky navrhujú CSS, takmer prichádza ako druhá povaha. Pomaly si zapamätáte všetky vlastnosti, syntax a vytvorte si vlastný systém pre šablóny so štýlmi. Prostredníctvom vlastnej práce som vytvoril to, čo nazývam zoskupenia spárovať podobné bloky CSS do jednej oblasti.

Keď sa vrátim k úpravám CSS, ľahko nájdem to, čo potrebujem, za niekoľko sekúnd. Spôsob, akým sa rozhodnete skupinové štýly, závisí výhradne od vás, a to je krása tohto systému. Mám niekoľko prednastavených štandardov, ktoré som opísal nižšie:

• - obnovuje predvolené okraje prehliadača, polstrovanie, písma, farby atď.
• @fonts - odseky, nadpisy, blockquotes, odkazy, kód
• @navigation - hlavné navigačné odkazy na hlavné webové stránky
• @layout - obal, kontajner, postranné lišty
• @header & @footer - tieto sa môžu líšiť podľa vášho dizajnu. Možné štýly zahŕňajú prepojenia a neusporiadané zoznamy, stĺpce päty, nadpisy, podstránky

Pri zoskupovaní šablón štýlov som našiel systém označovania môže pomôcť veľa. Na rozdiel od PHP alebo JavaScript však používam jeden @group značku, za ktorou nasleduje kategória alebo kľúčové slová. Nižšie som uviedol 2 príklady, aby ste získali pocit, čo tým myslím.

/ ** @group footer * / # footer štýly ...

/ ** @group päta, malé písma, stĺpce, externé odkazy ** / 

Môžete alternatívne pridať trochu ďalších detailov do každého bloku komentárov. Rozhodol som sa udržať veci jednoduché a jednoduché takže štýly sú ľahko odstrániteľné. Komentovanie je všetko o dokumentácii tak dlho, ako ste pochopili, že písanie je dobré!

4 tipy na lepšie komentovanie štýlu

Strávili sme prvú polovicu tohto článku a pozerali sme sa na rôzne formáty kódovania komentárov. Poďme teraz diskutovať o niektorých všeobecných tipoch na udržanie vášho kódu čistého, organizovaného a ľahko pochopiteľného.

1. Udržujte všetko čitateľné

Niekedy ako vývojári to zabúdame píšeme komentáre pre ľudí, aby si ich prečítali. Všetky programovacie jazyky, ktoré rozumieme, sú postavené na strojoch, takže môže byť únavné premeniť sa na jednoduchý písaný text. Je dôležité poznamenať, že nie sme tu, aby sme napísali výskumnú prácu na vysokej škole, ale len ponechať tipy!

funkcia getTheMail () // kód tu vytvorí e-mail / * spustiť kód, ak náš vlastný sendMyMail () funkčný hovor vráti true find sendMyMail () v /libs/mailer.class.php skontrolujeme, či používateľ vyplní všetky polia a správa je odoslaná! * / if (sendMyMail ()) return true; // udržiavať pravdu a zobraziť úspech na obrazovke

Dokonca sú len pár slov lepšie ako nič. Keď sa vrátite k tomu, aby ste v budúcnosti upravovali a pracovali na projektoch, je často prekvapujúce, koľko budete zabudnúť. Vzhľadom na to, že nevidíte každý deň rovnaké názvy premenných a funkcií, máte tendenciu pomaly zabúdať na väčšinu kódu. Tak môžete nikdy neopustiť príliš veľa pripomienok! Môžete však nechať príliš veľa zlých komentárov.

Ako všeobecné pravidlo, trvať nejaký čas na to, aby ste prestali písať. Opýtajte sa sami seba čo je najviac mätúce v súvislosti s programom a ako to najlepšie vysvetlíte “maketa” Jazyk? Zvážte tiež prečo píšete kód presne tak, ako ste.

Niektoré najzneužujúcejšie chyby sa objavia, keď zabudnete na účel vlastných (alebo tretích strán) funkcií. Zanechajte stopu pre komentáre, ktorá vedie k niekoľkým ďalším súborom ak vám to pomôže spomienkovať na funkčnosť.

2. Zmierniť nejaký priestor!

Nemôžem dostatočne zdôrazniť, aké dôležité Biely vesmír môže byť. Toto ide dvojnásobne pravda pre vývojárov PHP a Ruby, ktorí pracujú na masívnych webových stránkach so stovkami súborov. Budete sa pozerať na tento kód po celý deň! Nebolo by skvelé, keby ste mohli len prechádzať do dôležitých oblastí?

$ dir1 = "/ home /"; // nastaviť hlavný domovský adresár $ myCurrentDir = getCurDirr (); // nastaviť aktuálny používateľský adresár $ userVar = $ get_username (); // používateľské meno aktuálneho používateľa

V príklade vyššie si všimnete extra výplň, ktorú som umiestnil medzi komentármi a kódom na každom riadku. Pri prechode súborov tento štýl pripomienkovania jasne vyniknúť. to zjednodušuje hľadanie chýb a opravuje váš kód stokrát keď sú to premenné bloky čistý.

Môžete vykonať podobnú úlohu na kóde vnútri funkcie, kde ste zmätení o tom, ako to funguje, ale táto metóda by nakoniec neporiadok váš kód s inline komentáre, a to je presný opak usporiadané! Odporúčam v tomto scenári pridanie veľkej poznámky blokovej línie okolo oblasti logiky.

$ (document) .ready (funkcia () $ ('.sub)' skryť (); // skryť sub-navigáciu na pageload / ** skontrolovať kliknutie udalosti na kotve vo vnútri. akcia, takže sa stránka nezmení po kliknutí na prístup k nadradenému prvku .itm a potom k nasledujúcemu zoznamu .sub, aby sa prepínalo otvorené / zatvorené ** / $ ('. itm a') live ('click', funkcia ) e.preventDefault (); $ (to) .parent () nasledujúci ('.sub') slideToggle ('fast');););

Jedná sa o malý kúsok kódu jQuery, ktorý je zacielený na posuvnú navigáciu podmenu. Prvá poznámka je inline, aby sme vysvetlili, prečo skrývame všetky .náhradník triedy. Nad manipulátorom udalostí naživo kliknite na komentár a odsadil všetko písanie do toho istého bodu. To robí veci skôr lacinými než bežiacimi odsekmi - najmä pre ostatných, ktorí čítajú vaše pripomienky.

3. Komentár pri kódovaní

Spolu so správnym rozstupom môže byť jedným z najlepších návykov, ktorým sa môžete dostať. Nikto sa nechce vrátiť späť do svojho programu po tom, čo pracuje a dokumentuje každý kus. Väčšina z nás sa ani nechce vrátiť a zdokumentovať zmätené oblasti! Naozaj to veľa práce.

Ak však môžete písať komentáre počas kódovania všetko bude stále vo vašej mysli čerstvé. Vývojári sa zvyčajne uviaznu na probléme a vyhľadávajú web na najjednoduchšie riešenie. Keď narazíte na moment Eureky a vyriešite takýto problém, zvyčajne je chvíľka jasná, keď rozumiete vašim predchádzajúcim chybám. Toto by bolo najlepší čas nechať otvorené a čestné komentáre k vášmu kódu.

Navyše vám to prinesie prax, aby ste si zvykli komentovať všetky svoje súbory. Čas potrebný na návrat a zistenie, ako funguje niečo, je oveľa väčšie po tom, čo ste už funkciu postavili. Vaša budúca seba a Vaši spoluhráči vám poďakujú za to, že ste vopred zanechali pripomienky.

4. Zaobchádzanie s bugmi chyby

Nemôžeme všetci sedieť pred počítačom hodiny písať kód. Myslím, že to môžeme vyskúšať, ale v určitom okamihu musíme spať! Budete pravdepodobne musieť rozdeliť spôsoby s vaším kódom pre deň s niektorými funkciami stále rozbité. V tomto scenári je veľmi dôležité, aby ste vy nechajte dlhé, podrobné poznámky o tom, kam ste nechali veci.

Dokonca aj po čerstvom nočnom spánku vás možno prekvapí, aké ťažké môže byť návrat do hojdačky kódovania. Napríklad, ak vytvárate stránku na odovzdávanie obrázkov a necháte ju nedokončená, vy mali by sa vyjadriť k tomu, kde ste v procese prestali. Sú obrázky odovzdávané a uložené v dočasnej pamäti? Alebo možno ani nie sú rozpoznané vo formulári na odovzdanie, alebo sa možno po načítaní stránky na stránke správne nezobrazia.

Komentovanie chýb je dôležité z dvoch hlavných dôvodov. Najprv môžete ľahko vyzdvihnúť tam, kde ste prestali a skúste znova čerstvé na mysli, aby ste vyriešili problém (-y). A za druhé môžete rozlišujte medzi verziou vašej webovej stránky naživo a skúšobným priestorom. Nezabudnite, že by sa mali používať pripomienky vysvetliť, prečo robíte niečo, nie presne to, čo robí.

záver

Vývoj webových aplikácií a softvéru je naplniteľnou praxou, aj keď je náročná. Ak ste jedným z mála vývojárov, ktorí skutočne chápu softvér na stavbu, potom je dôležité, aby ste sa zrelili svojimi kódovacími schopnosťami. Ponechanie opisných komentárov je z dlhodobého hľadiska iba dobrou praxou, a pravdepodobne nikdy nebudete ľutovať!

Ak máte návrhy na jasnejšie komentovanie kódu, dajte nám vedieť v diskusnej oblasti nižšie!