Názorný průvodce styly kódování pro Angular

Interní průvodce stylem pro psaní kódu je důležité rozhodnutí, které by měl každý vývojový tým definovat a dohodnout se na něm v určitém okamžiku, ideálně na začátku projektu.

Tento článek byl původně publikován na webu Bits and Pieces od Giancarla Buomprisca

Pokud píšete kód profesionálně, velmi dobře víte, jak důležitý je styl pro mnoho a mnoho vývojářů. Nespočet hodin v mé kariéře jsem strávil hádkami o stylu.

Proč je to však tak důležité? Programátoři mnohem více kód čtou, než píší :je klíčové, abychom tento úkol co nejvíce zjednodušili pro nás, ale především pro naše spoluhráče.

Shoda spočívá v definování průvodce stylem před napsáním prvního řádku kódu, ale toto by nemělo být stanoveno pro celý životní cyklus projektu:je to nepřetržitý soubor poznatků odvozených z experimentování a zkušeností.

Neznamená to také, že byste měli měnit svůj názor každý den:znamená to, že byste měli hodnotit, diskutovat a rozhodovat se se svým týmem, jak váš projekt roste.

Poté, co jsem od dob alfa psal aplikace Angular, vyvinul jsem svůj styl, silně ovlivněný lidmi, se kterými jsem pracoval, četl jsem kódy mnoha lidí a jednoduše experimentoval se svými projekty.

V tomto článku chci ukázat, jak stylizuji své aplikace Angular a zdůvodnění mých rozhodnutí. Doufejme, že to bude inspirovat vás a váš tým, abyste si něco z toho osvojili nebo si vytvořili vlastní.

Jakékoli návrhy, jak to zlepšit, uvítáme!

Upozornění :tato příručka stylu je čistě stylistická a nezakládá se na technických detailech a osvědčených postupech. Tento průvodce stylem má jednoduše pomoci s estetikou a čitelností kódu , nikoli výkon, designové vzory nebo jiné.

Kromě dodržování určitého průvodce stylem je důležité používat nástroje, díky kterým bude váš kód snadno pochopitelný, udržitelný a znovu použitelný (ostatními ve vaší organizaci nebo dokonce komunitou open source). Jeden nástroj, který rád používám Bit.dev.

Obtékání a objednávka HTML

Šablony Angular mají oproti normálnímu HTML několik dodatků k syntaxi a někdy nejsou příliš snadno čitelné.

Můj první návrh se týká obalu. Obvykle nepřekračuji 80 znaků na sloupec pro všechny soubory:je jednoduše mnohem jednodušší číst svisle než vodorovně.

Toto je prvek napsaný bez jakékoli konvence:

Nepořádek, že? Téměř každý projekt, na kterém jsem během poradenství pracoval, byl napsán podobným způsobem.

Výše uvedený úryvek přepíšeme pomocí sady jednoduchých pravidel, aby byl čitelnější.

Definování pravidel pro psaní HTML značek

• Když má prvek dva nebo více atributů, obvykle napíšu pouze jeden atribut na řádek

• Atributy musí být napsány v určitém pořadí

• Pokud nepoužíváte jediný atribut, musí být uzavírací značka napsána na dalším řádku

Navrhuji definovat konkrétní objednávku:

• Strukturální směrnice

• Animace

• Statické vlastnosti

• Dynamické vlastnosti

• Události

Podívejme se na příklad, jak bych osobně napsal předchozí příklad:

Ještě lepší je, že bych vždy používal strukturální směrnice výhradně s ng-container:

I když si myslím, že si můžete zamíchat pořadí atributů na základě subjektivního pohledu, cítím se docela pevně, pokud jde o zobrazování strukturálních směrnic před čímkoli jiným .

Strukturální směrnice mi říká (než potřebuji vědět cokoli dalšího, co to dělá):

• Zobrazuje se toto pole? A proč?

• Opakuje se toto pole?

Podle mého názoru to může usnadnit čtení a pochopení struktury vašich šablon.

Potrubí

Trubky jsou velmi výkonné:mohou transformovat hodnoty v šablonách a vyhnout se duplicitě/logice v našich komponentách. Mohou být znovu použity a snadno smíchány a snadno se píší.

Jsou ale snadno čitelné a rozpoznatelné? Ano a Ne.

Toto je vysoce subjektivní a podružný bod, ale přesto si myslím, že může být cenné se o to podělit:kdykoli vidím ve své šabloně dýmku, mám tendenci je zabalit do závorek. Pocit rozdělení, který poskytuje závorka, mi dává tušit, že hodnota se transformuje a obecně je pro oko jednodušší:

Při použití více potrubí může být ještě důležitější:

Háčky životního cyklu

Rozhraní

Přidání rozhraní háčků životního cyklu není povinné, ale doporučený postup, který důrazně doporučuji dodržovat.

Objednávka

Když hledám háčky životního cyklu, obvykle zamířím ke konstruktoru a očekávám, že je uvidí všechny pohromadě a nepletou se s jinými metodami třídy. V ideálním případě by měly být definovány ve stejném pořadí, v jakém se provádějí.

Doporučuji:

• vždy přidávejte rozhraní

• přidat veřejné a soukromé vlastnosti nad konstruktor

• přidat metody přímo pod konstruktor a nad metody komponenty

• přidejte je všechny blízko sebe

• přidejte je v pořadí, v jakém provádějí. Je však pravda, že toto je trochu těžší důsledně dodržovat, takže si myslím, že je to nejméně důležité

Logika

Obvykle se vyhýbám přímému psaní jakékoli logiky v rámci háčků životního cyklu:můj návrh je zapouzdřit logiku do soukromých metod a volat je v rámci háčků životního cyklu:

Vlastnosti a metody komponenty

Angular používá dekorátory pro metody a vlastnosti komponenty, aby rozšířil její funkčnost.

Je jich tolik, že definovat konkrétní pořadí, které se má následovat, by bylo zdrcující, ale důležitá věc, kterou se snažím dodržovat, je najít vlastnosti a metody se stejným dekorátorem blízko sebe.

Následující příklad bych považoval za špatný:

A níže je, jak bych to napsal; také si všimněte, že mezi skupinami vlastností se stejným dekorátorem je prázdný řádek – myslím, že to pomáhá s čitelností:

Nemám na to vyhraněný názor, ale pokuste se najít soukromé a veřejné komponenty, které nejsou označeny žádným dekoratérem, odděleně od dekorovaných nemovitostí.

Podle mých zkušeností vede jejich smíchání pouze ke zmatku a pocitu chaosu.

Pojmenování

Oh, pojmenovat věci je těžké, já vím.

Co se týče pojmenování, musím si to vždy dvakrát nebo více rozmyslet, abych našel název, který je srozumitelný, jednoznačný a snadno dohledatelný:

• srozumitelné :co to dělá, na první pohled?

• jednoznačné :například pokud máme více událostí kliknutí na jednu komponentu, na kterou z nich se tato událost vztahuje? Takže ano, pojmenujte to onClick není cesta, kterou jít

• snadné vyhledávání :Jmenovací kód vidím trochu jako SEO:jak budou moji uživatelé (spoluhráči nebo já) hledat tuto konkrétní věc – a jak ji mohu napsat, abych se ujistil, že ji budou moci hledat snadněji?

Názvy souborů

Rád používám pomlčku-case pro všechny názvy souborů. Myslím, že už je to standard pro projekty Typescript, ale viděl jsem docela dost variací, dokonce i v projektech Angular, takže mám pocit, že to musím zmínit.

Příklady:

• sign-up.component.ts

• profile-form.component.html

Komponenty trasy

Mám tendenci pojmenovávat komponenty trasy pomocí stránky s příponou.

Ověřovací stránka by se například normálně jmenovala auth-page.component.ts – což mi říká, že jde o směrovanou komponentu a normálně ji používám k zabalení a zobrazení dalších komponent přes router-outlet.

Komponenty

Některá pravidla, která mám tendenci dodržovat při pojmenovávání komponent, jsou:

• Pokuste se použít ne více než 3 slova (kromě předpony). Žádný konkrétní důvod proč – prostě nevypadají moc hezky. Samozřejmě, někdy to prostě není snadné respektovat toto pravidlo

• Snažte se vyvarovat opakování již použitých slov nebo kontextů s jinými komponentami, protože by se to zpomalilo při používání vyhledávací funkce mého IDE a také by to vedlo k mylnému otevírání jiných souborů, což je v konečném důsledku ztráta času a zdroj frustrace

• Zároveň se snažte nebýt příliš obecný . Například:nazveme-li komponentu nastavení — nastavení čeho!? Zde trochu pomozte a uveďte další kontext (příklad:nastavení aplikace, nastavení profilu, nastavení organizace atd.).
  Pro malé aplikace to není nic extra, ale v měřítku to dělá rozdíl

Názvy událostí

Zdá se to jednoduché, ale není, zvláště u větších komponent s mnoha událostmi.

Zde je soubor pravidel, která se snažím dodržovat:

• Nepřidávejte před názvy událostí/výstupů on. Obslužný program by místo toho mohl být zapsán s takovou předponou

• Nenuťte mě přemýšlet:vždy uveďte entitu, jejíž akce se týkala, nikoli pouze akci samotnou.
  Pokud popisujeme událost na komponentě, jejíž hodnota se změnila, změna události by mohla být valueChange.
  Podle mého názoru je to jednoznačné a říká mi to, co se změnilo, aniž bych se zeptal, jestli to byla hodnota, stav nebo cokoli jiného

• Použít minulý smysl nebo ne (valueChange vs valueChanged)? To je kontroverzní a slyšel jsem pádné důvody na opačných stranách, takže to může být k diskusi pro vás a váš tým.
  Pokud se shodnete na jedné jednosměrce, nemyslím si, že to je tak Důležité. Co si o tom myslíte?

Import ES

Udržování uspořádaných a úhledných importů souborů je náročné, zvláště když k jejich automatickému přidávání během psaní používáte IDE. Jak vaše soubory rostou, mají tendenci být docela chaotické.

Takto objednávám své dovozy:

• Úhlové importy jsou vždy nahoře

• Rx import

• Třetí strany (jiné než jádro)

• Místní/projektové importy na konci

Je také dobré zanechat komentář nad každou skupinou:

Jídlo s sebou ⭐

• Úhledně zabalte prvky HTML:umístěte 1 samostatný atribut na řádek a seřaďte atributy podle typu

• Použijte závorky kolem hodnot, které používají svislé čáry

• Umístěte háčky životního cyklu vedle sebe a seřaďte je podle pořadí provedení

• Když věci pojmenováváte, zeptejte se sami sebe:je to srozumitelné, jednoznačné a snadno dohledatelné?

• Udržujte importy ES čisté a uspořádané

Opinionated Angular

Přidal jsem úložiště Github nazvané Opinionated Angular, kam budu ukládat více svých myšlenek pro psaní čitelného a krásného kódu Angular.

Pokud chcete, přijďte a přispějte!

Rád bych obdržel nějaké tipy a dozvěděl se o vašich konvencích a pravidlech, kterými se vy a váš tým řídíte. Případně, pokud potřebujete nějaké vysvětlení nebo si myslíte, že je něco nejasné nebo špatně, zanechte prosím komentář!

Doufám, že se vám tento článek líbil! Pokud ano, sledujte mě na Medium, Twitteru nebo Dev pro další články o vývoji softwaru, frontendu, RxJS, Typescript a dalších!