Zdrojový kód Komentář Styling Tips a Best Practices

Vývojáři, kteří strávili nějaký čas na velkých projektech, chápou důležitost kódových poznámek. Když stavíte mnoho funkcí do stejné aplikace, věci mají tendenci být komplikované. Existuje tolik datových bitů, včetně funkcí, referencí proměnných, návratových hodnot, parametrů… jak se očekává, že budete držet krok?

Mělo by přijít jako žádné překvapení, že komentování kódu je nezbytné, a to jak sólové, tak týmové projekty. Ale mnoho vývojářů si neuvědomuje, jak v tomto procesu postupovat. Načrtl jsem některé z mých vlastních osobních triků vytváření čistých, formátovaných komentářů kódu. Standardy a šablony šablon se budou mezi vývojáři lišit - ale nakonec byste se měli snažit čisté a čitelné komentáře dále vysvětlit matoucí oblasti kódu.

Měli bychom začít diskutovat o některých rozdílech ve formátování komentářů. To vám dá lepší představu o tom, jak podrobně se můžete stát s kódem projektu. Poté vám nabídnu několik konkrétních tipů a příkladů, které můžete hned začít používat!

Styly komentářů: Přehled

Je třeba poznamenat, že tyto představy jsou pouze pokyny k čistším připomínkám. Jednotlivé programovací jazyky neobsahují pokyny ani specifikace pro nastavení dokumentace.

To znamená, že moderní vývojáři se seskupili, aby formátovali svůj vlastní systém komentování kódu. Nabídnu několik mainstreamových stylů a jdu do detailu jejich účelu.

Inline komentování

Prakticky každý jednotlivý programovací jazyk nabízí inline komentáře. Ty jsou omezeny na jednořádkový obsah a text komentují pouze po určitém bodě. Tak například v C / C ++ začínáte inline komentář takto:

// zahajuje seznam proměnných var myvar = 1;… 

To je ideální pro napodobování kódu po dobu několika sekund vysvětlit případné matoucí funkce. Pokud pracujete se spoustou parametrů nebo funkcí volání, můžete umístit zabité inline komentáře poblíž. Ale nejpřínosnější použití je jednoduché vysvětlení pro malé funkce.

if (callAjax ($ params)) // úspěšně spustit callAjax s uživatelskými parametry… code

Všimněte si, že kód musí být na novém řádku za úvodní závorkou. V opačném případě by všechny byly zachyceny na stejné řádce komentáře! Vyhněte se přes palubu vzhledem k tomu, že obvykle nemusíte vidět jednotlivé řádky po celé stránce, ale zejména pro matoucí křižovatky ve vašem kódu, je mnohem snazší je v poslední chvíli zrušit.

Popisné bloky

Pokud potřebujete zahrnout velké vysvětlení obecně, jediná vložka nebude stačit. V každé oblasti programování se používají předformátované šablony komentářů. Popisné bloky jsou vidět především kolem funkcí a knihovních souborů. Kdykoliv nastavíte novou funkci, je to dobrá praxe nad deklaraci přidejte popisný blok.

/ ** * @desc otevře modální okno pro zobrazení zprávy * @param řetězec $ msg - zpráva, která má být zobrazena * @ return bool - úspěch nebo neúspěch * / funkce modalPopup ($ msg) … 

Nahoře je jednoduchý příklad popisu popisné funkce. Jsem napsal funkci pravděpodobně v JavaScriptu volal modalPopup který má jeden parametr. Ve výše uvedených komentářích jsem použil syntaxi podobnou phpDocumentor, kde každé řádce předchází znak a @ symbol následovaný vybraným tlačítkem. Ty nebudou mít žádný vliv na váš kód, takže byste mohli psát @popis namísto @desc bez jakýchkoliv změn.

Tyto malé klíče jsou vlastně nazývány komentáře které jsou na webové stránce zdokumentovány. Neváhejte si vytvořit svůj vlastní a používat tyto, jak budete chtít v celém kódu. Připadá mi, že pomáhají udržet vše, co proudí Na první pohled mohu zkontrolovat důležité informace. Měli byste si také všimnout, že jsem použil / * * / formát komentáře ve stylu bloků. To všechno udrží mnohem čistší než přidáním dvojité lomky začínající na každém řádku.

Poznámky ke skupině / třídě

Kromě komentování funkcí a smyček nejsou oblasti bloků využívány tak často. Kde opravdu potřebujete silný blokovat komentáře jsou v čele vašich backendových dokumentů nebo knihovních souborů. Je to snadné jít all-out a napsat solidní dokumentaci pro každý soubor na vašich webových stránkách - můžeme vidět tuto praxi v mnoha CMS, jako je WordPress.

Horní část stránky by měla obsahovat komentáře týkající se samotného souboru. Tímto způsobem můžete rychle zkontrolujte, kde editujete při práci na více stránkách najednou. Navíc můžete tuto oblast použít jako databáze nejdůležitějších funkcí, které budete potřebovat mimo třídu.

/ ** * @desc tato třída bude obsahovat funkce pro interakci uživatele * příklady zahrnují user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstraktní třída myWebClass  

Můžete vidět, že jsem použil jen malou ukázkovou třídu pro falešné myWebClass kód. Přidal jsem nějaké meta informace s mým jménem a e-mailovou adresou pro kontakt. Když vývojáři píšou open source kód, je to obecně dobrá praxe, takže ostatní vás mohou kontaktovat pro podporu. To je také solidní metoda při práci ve větších vývojových týmech.

Značka @Povinný není něco, co jsem viděl jinde. V několika mých projektech jsem držel krok s formátem, pouze na stránkách, kde jsem si přizpůsobil spoustu metod. Kdykoliv vložíte stránky do souboru, musí být před odesláním kódu. Přidání těchto údajů do bloku komentáře hlavní třídy je tedy dobrým způsobem pamatujte si, které soubory jsou potřeba.

Front-end Code Commenting

Nyní, když jsme se zabývali 3 důležitými šablonami komentářů, podívejme se na několik dalších příkladů. Existuje mnoho vývojářů, kteří přecházeli ze statického HTML do jQuery a CSS kódu. Komentáře ve formátu HTML nejsou ve srovnání s aplikacemi pro programování tak účelné, ale když píšete knihovny stylů a skripty stránek, časem se může stát, že se věci dostanou do nepořádku..

JavaScript následuje tradičnější způsob komentování podobný jazyku Java, PHP a C / C++. CSS využívá pouze blokové komentáře vymezené lomítkem a hvězdičkou. Měli byste pamatovat, že komentáře budou otevřeně zobrazeny návštěvníkům, protože ani CSS, ani JS nejsou analyzovány na straně serveru, ale každá z těchto metod funguje skvěle pro zanechání informativních tidbits ve vašem kódu, aby se vrátila zpět..

Konkrétně rozbití CSS souborů může být fuška. Všichni jsme obeznámeni s zanecháním komentáře, který vysvětluje opravu aplikace Internet Explorer nebo Safari. Ale věřím, že CSS komentování může být použito na úrovni jQuery a PHP je používá. Pojďme se ponořit do vytváření skupin stylů, než se dotkneme některých podrobných tipů pro komentování kódu.

Skupiny stylů CSS

Pro ty, kteří již několik let navrhují CSS, přichází téměř jako druhá příroda. Pomalu si zapamatujete všechny vlastnosti, syntaxi a vytvoříte vlastní systém pro styly. Prostřednictvím své vlastní práce jsem vytvořil to, čemu říkám seskupení párovat podobné CSS bloky do jedné oblasti.

Když se vrátím zpět k úpravě CSS, můžu snadno najít to, co potřebuju během několika sekund. Způsob, jakým se rozhodnete seskupovat styly, je zcela na vás, a to je krása tohoto systému. Mám několik přednastavených standardů, které jsem popsal níže:

• @resets - odebrání výchozích okrajů prohlížeče, vycpávky, písma, barev atd.
• @ fonts - odstavce, záhlaví, blockquotes, odkazy, kód
• @ Navigace - hlavní hlavní navigační odkazy na webové stránky
• @layout - wrapper, kontejner, postranní lišty
• @header & @footer - mohou se lišit v závislosti na vašem návrhu. Mezi možné styly patří odkazy a neuspořádané seznamy, sloupce zápatí, záhlaví, dílčí navigace

Při seskupování stylů jsem našel systém značkování může hodně pomoci. Nicméně na rozdíl od PHP nebo JavaScriptu používám jeden @skupina tag následovaný kategorií nebo klíčovými slovy. Níže jsem uvedl 2 příklady, takže můžete získat pocit, co myslím.

/ ** @group footer * / #footer styles…

/ ** @ zápatí skupiny, malá písma, sloupce, externí odkazy ** / 

Alternativně můžete v každém bloku komentářů přidat trochu dalších podrobností. Rozhodl jsem se udržet věci jednoduché a přímočaré takže stylesheety jsou snadno sbírat. Připomínka je o dokumentaci tak dlouho, dokud pochopíte, že psaní je dobré jít!

4 tipy na lepší komentář Styling

První polovinu tohoto článku jsme strávili při pohledu na různé formáty pro komentování kódu. Pojďme nyní diskutovat o některých obecných tipech, jak udržet váš kód čistý, organizovaný a snadno pochopitelný.

1. Udržujte vše čitelné

Někdy jako vývojáři na to zapomínáme píšeme komentáře pro lidi ke čtení. Všechny programovací jazyky, kterým rozumíme, jsou konstruovány pro stroje, takže může být únavné převádět na prostý psaný text. Je důležité poznamenat, že nejsme tady, abychom mohli napsat výzkumnou práci na vysoké škole, ale jen opouštět tipy!

funkce getTheMail () // kód zde bude stavět e-mail / * run kód, pokud naše funkce callMyMail () funkce vrátí true find sendMyMail () v /libs/mailer.class.php zkontrolujeme, zda uživatel vyplní všechna pole a zpráva je odeslána! * / if (sendMyMail ()) return true; // zachovat pravdivost a zobrazit úspěch na obrazovce

Dokonce jen pár slov lepší než nic. Když se vrátíte k úpravám a práci na projektech v budoucnu, je to často překvapující, kolik zapomenete. Vzhledem k tomu, že se každý den díváte na stejné proměnné a názvy funkcí, máte tendenci pomalu zapomínat na většinu kódu. Tak můžete nikdy nenechávejte příliš mnoho komentářů! Ale můžete zanechat příliš mnoho špatných komentářů.

Jako obecné pravidlo, nějakou dobu trvat, než se pustíte a přemýšlíte před psaním. Zeptejte se sami sebe co je na programu nejvíce matoucí a jak to můžete nejlépe vysvětlit “figuríny” Jazyk? Také zvážit Proč píšete kód přesně tak, jak jste.

Některé z nejvíce matoucí chyby vyskočí, když zapomenete na účel vlastní-postavený (nebo třetí strany) funkce. Nechte komentář stezka vedoucí zpět na několik dalších souborů pokud vám to pomůže zapamatovat si funkčnost jednodušší.

2. Zmírnit prostor!

Nemohu dostatečně zdůraznit, jak důležité mezery může být. To jde dvojnásobně pravda pro vývojáře PHP a Ruby, kteří pracují na masivních webech se stovkami souborů. Budete celý den hledět na tento kód! Nebylo by skvělé, kdybyste se mohli dostat do důležitých oblastí?

$ dir1 = "/ home /"; // nastavit hlavní domovský adresář $ myCurrentDir = getCurDirr (); // nastavte aktuální uživatelský adresář $ userVar = $ get_username (); // aktuální uživatelské jméno uživatele

Ve výše uvedeném příkladu si všimnete extra polstrování, které jsem umístil mezi komentáře a kód na každém řádku. Jak budete procházet soubory, tento styl komentování bude jasně vyčnívají. To usnadňuje nalezení chyb a opravu kódu když proměnné bloky jsou čistý.

Podobný úkol byste mohli provádět na kódu uvnitř funkce, kde jste zmateni, jak to funguje, ale tato metoda by nakonec kód zaplnila s vloženými komentáři, a to je přesný opak řádného! Doporučuji v tomto scénáři přidáním velké blokové řádky kolem oblasti logiky.

$ (document) .ready (function () $ ('. sub'). hide (); // skrýt dílčí navigaci na stránce loadload / ** zkontrolovat událost kliknutí na kotvu uvnitř .itm div zabránit výchozímu odkazu akce tak, že se stránka nezmění po kliknutí na nadřazený prvek .itm následovaný dalším seznamem .sub pro přepínání open / close ** / $ ('. itm a') live ('click', funkce (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Jedná se o malý kousek kódu jQuery, který cílí na dílčí nabídku posuvné navigace. První poznámka je inline vysvětlit, proč se schováváme všechny .sub třídy. Nad obslužnou rutinou události klikání jsem použil komentář bloku a všechny písmo do stejného bodu. To dělá věci hezčí, spíše než run-on odstavce - zejména pro ostatní čtení vašich komentářů.

3. Komentář při kódování

Spolu se správným odstupem to může být jeden z nejlepších návyků, do kterých se můžete dostat. Nikdo se nechce vrátit přes svůj program poté, co bude pracovat a dokumentovat každý kus. Většina z nás se ani nechce vrátit a dokumentovat matoucí oblasti! Je to opravdu hodně práce.

Ale pokud můžete psát komentáře, zatímco jste kódování vše bude ve vaší mysli stále čerstvé. Typicky vývojáři uvíznou na problému a vyčistí web pro nejjednodušší řešení. Když narazíte na okamžik Eureky a vyřešíte takový problém, je obecně jasná chvíle, kdy pochopíte vaše předchozí chyby. To by bylo nejlepší čas nechat otevřené a čestné komentáře o vašem kódu.

Kromě toho vám dá praxi zvyknout si na komentování všech vašich souborů. Množství času potřebné k návratu a zjistit, jak něco funguje, je mnohem větší, když jste již tuto funkci vytvořili. Vaše budoucí já i vaši spoluhráči vám děkují za zanechání komentářů v předstihu.

4. Řešení chyb Buggy

Nemůžeme všichni sedět v přední části počítače na hodiny psaní kódu. Předpokládám, že to můžeme zkusit, ale v určitém okamžiku musíme spát! Pravděpodobně budete muset rozdělit způsoby s kódem pro daný den s některými funkcemi, které jsou stále rozbité. V tomto scénáři je klíčové, abyste vy nechte dlouhé, podrobné komentáře o tom, kde jste věci opustili.

Dokonce i po čerstvém nočním spánku můžete být překvapeni, jak těžké může být dostat se zpět do švihu kódování. Například, pokud vytváříte stránku pro nahrávání obrázků a musíte ji nechat nedokončenou, vy by měl komentovat, kde v procesu jste přestali. Jsou obrázky nahrávány a ukládány do paměti temp? Nebo možná nejsou ani rozpoznány ve formuláři pro nahrávání nebo se po nahrání na stránce nezobrazují správně.

Chyby komentování jsou důležité ze dvou hlavních důvodů. Nejdřív můžete snadno zvedněte tam, kde jste přestali a zkuste znovu vyřešit problém (y). A za druhé můžete rozlišovat mezi živou produkční verzí vašich webových stránek a testovacími důvody. Nezapomeňte, že by měly být použity komentáře vysvětlete, proč něco děláte, není přesně to, co dělá.

Závěr

Vývoj webových aplikací a softwaru je plnohodnotnou praxí, i když obtížnou. Pokud jste jedním z mála vývojářů, kteří skutečně chápou stavební software, je důležité vyzrát se svými schopnostmi kódování. Ponechání popisných komentářů je z dlouhodobého hlediska jen dobrou praxí, a pravděpodobně to nikdy nebudete litovat!

Pokud máte návrhy na jasnější komentování kódu, dejte nám vědět v diskusní oblasti níže!