Manual:Coding conventions/JavaScript/cs

Tato stránka popisuje kódovací konvence pro JavaScript v MediaWiki codebase. Viz také obecné konvence.

Odkazování
Jako náš nástroj pro kvalitu kódu používáme ESLint s přednastavením eslint-config-wikimedia pro kódování většiny našich stylů kódování a pravidel kvality kódu. Na stránce Integrations na eslint.org najdete mnoho textových editorů nebo IDE s pluginy, které poskytují živou zpětnou vazbu při psaní.



Konfigurace Linter
Chcete-li z analýzy vyloučit soubory nebo adresáře (např. knihovny třetích stran), můžete konfigurovat vzory ignorování v ESLint prostřednictvím souboru. Všimněte si, že  je ve výchozím nastavení vyloučen, takže většina repozitářů nemusí nastavovat žádná pravidla ignorování.

Každé repo potřebuje soubor  v kořenovém adresáři úložiště. Následuje příklad konfiguračního souboru ESLint:

Živé příklady viz .eslintrc.json v MediaWiki a VisualEditoru.

Nezapomeňte nastavit, abyste předešli nechtěnému "magickému dědění" konfigurací ESLint v nesouvisejících nadřazených adresářích, které jste vy nebo server CI mohli nastavit na disku (například mezi rozšířením MediaWiki a jádrem MediaWiki nebo mezi vaším projektovým adresářem a něčím v váš domovský adresář).

Přednastavení eslint-config-wikimedia poskytuje několik profilů, ze kterých si mohou projekty vybrat, jak uznají za vhodné, jako jsou různé jazykové příchutě nebo globální prostředí běhového prostředí. Například:


 * - pro kód prohlížeče a očekává podporu ES5
 * - pro kód prohlížeče, který používá ES6
 * - pro kód Node.js 10+ a očekává podporu ES2018
 * - mix pro testy QUnit

Měli byste očekávat použití více souborů  v repo pro nastavení různých environmentálních očekávání pro různé podadresáře. Tím je zajištěno, že nepoužijete náhodou metody  v kódu serveru, který očekáváte na serveru, nebo že v produkčním kódu neodkážete na QUnit. soubory v podadresářích automaticky dědí z konfigurace nadřazeného adresáře, takže musí obsahovat pouze věci, které jsou specifické pro daný adresář (example file).



Nepřetržitá integrace
Projektům se doporučuje, aby prosadily předávání ESLint tím, že do něj zahrnou svůj  skript pomocí příkazu "test" do. Více informací o tom najdete na Continuous integration/Entry points.

Pokud má váš projekt poměrně náročný testovací kanál, lze definovat skript  nebo dokonce   v , aby bylo snadné spouštět pouze ty z příkazového řádku během místního vývoje (abyste nemuseli otevírat každý soubor v editoru a/nebo čekat na CI).

Chcete-li odhalit další funkce příkazového řádku z ESLint (jako je lintování jednotlivých souborů mimo textový editor nebo použití funkce --fix), definujte "eslint" jako vlastní skript v package.json bez jakéhokoli argumentu. Poté jej můžete vyvolat z příkazového řádku následovně:

Mezery
Používáme následující konvence:


 * Odsazení s tabulátory.
 * Žádné mezery na konci.
 * Oddělení jednoho bloku logicky souvisejícího kódu od druhého pomocí prázdných řádků.
 * Jedna mezera na obou stranách binárních operátorů a operátorů přiřazení.
 * Klíčová slova následovaná " " (levá závorka) musí být oddělena jednou mezerou. To poskytuje vizuální rozlišení mezi klíčovými slovy a vyvoláním funkcí.
 * Mezi názvem funkce a levou závorkou seznamu argumentů by neměla být žádná mezera.
 * Uvnitř závorek (jako jsou příkazy if, volání funkcí a seznamy argumentů) by měla být jedna mezera.
 * Nepoužívejte operátory, jako by to byly funkce (například,  ,  ,  ,  , ..).

Tyto a další aspekty našeho průvodce stylem jsou vynuceny pomocí ESLint.



Délka řádku
Řádky by neměly být delší než 80–100 znaků. Pokud se příkaz nevejde na jeden řádek, rozdělte příkaz na více řádků. Pokračování prohlášení by mělo být odsazeno o jednu úroveň navíc.

Volání funkcí a objekty by měly být buď na jednom řádku, nebo rozděleny na více řádků s jedním řádkem pro každý segment. Vyvarujte se zavírání volání funkce nebo objektu v jiném odsazení, než je jeho otevření.

Struktura
Ve zkratce:

Uzavření
Pokud balíček modulů nelze nebo z jiného důvodu ještě není registrován pomocí, pak by jeho jednotlivé soubory JavaScriptu měly mít kolem kódu uzávěr na úrovni souboru. To dává kódu jeho vlastní rozsah a zabraňuje úniku proměnných z nebo do jiných souborů, včetně režimu ladění, a způsobem, který je srozumitelný pro statickou analýzu. Tento vzor je známý jako ihned vyvolaný funkční výraz (nebo "iffy").

U souborů balíčků to není potřeba, protože se spouštějí jako soubor "modul" spíše než soubor "script", který má přirozeně svůj vlastní lokální rozsah. ESLint by měl být také nakonfigurován odpovídajícím způsobem (nastavte, jako v tomto příkladu).

Prohlášení
Proměnné musí být deklarovány před použitím. Každé zadání musí být na samostatném řádku. Proměnné mohou být deklarovány blízko nebo při jejich prvním přiřazení.

Pokud kombinujete více přiřazení  v jednom příkazu, pak deklarace, které nepřiřazují hodnotu, by měly být uvedeny před přiřazením. Následující řádky by měly být odsazeny o další úroveň.

Funkce by měly být deklarovány před použitím. V těle funkce by deklarace funkcí měly následovat po deklaracích proměnných a před jakýmikoli hlavními příkazy.

Komentáře
Komentáře by měly být na samostatném řádku a měly by být nad kódem, který popisují.

V rámci komentáře by měla být úvodní syntaxe (např. lomítko-lomítko nebo lomítko-hvězda) oddělena od textu jednou mezerou a text by měl začínat velkým písmenem. Pokud je komentář platnou větou, měla by být na jejím konci umístěna tečka.

Používejte řádkové komentáře ve funkcích a dalších blocích kódu (včetně víceřádkových komentářů).

Používejte blokové komentáře pouze pro bloky dokumentace. To pomáhá udržovat konzistentní formátování vkládaných komentářů (např. ne některé jako bloky a některé jako víceřádkové komentáře nebo nutnost převádět z jednoho na druhý). Vyhnete se také matoucím dokumentačním enginům. Usnadňuje také deaktivaci částí kódu během vývoje pouhým posunutím zápisu koncového komentáře o několik řádků dolů, aniž by byl zkratován vloženým blokovým komentářem.

Buďte v komentářích liberální a nebojte se kvůli tomu velikosti souboru. Veškerý kód je před odesláním automaticky minimalizován o.



Komentáře k dokumentaci

 * Text v blocích volného tvaru by měl být velkými a malými písmeny (např. popis metod, parametrů, návratových hodnot atd.)
 * Věty začínejte velkým písmenem.
 * V popisu pokračujte na dalším řádku, odsazeném o jednu mezeru navíc.



Vygenerovaná dokumentace

 * V současné době přecházíme z JSDuck na, protože první je neudržovaný.

Níže uvedené bude aktualizováno, jakmile bude JSDoc přijato do jádra MediaWiki.

K vytvoření dokumentace použijte JSDuck (viz https://doc.wikimedia.org).

JSDuck je předinstalovaný v nových prostředích a ve WMF CI. Chcete-li jej nainstalovat do vlastního vývojářského prostředí, použijte k instalaci z RubyGems. Další informace naleznete na stránce průvodce.

Pro vygenerování dokumentace by měl být použit , jak je definováno v.

Nakonfigurujte JSDuck ve svém projektu pomocí souboru. Viz konfigurace JSDuck nebo zkontrolujte příklady pro MediaWiki.

Značky - tagy
Používáme následující anotace. Z důvodu konzistence by měly být použity v pořadí, jak jsou zde popsány. Viz dokumentace JSDuck, jak to funguje.

Typy
Primitivní typy a speciální hodnoty: boolean, číslo, řetězec, nedefinováno, null.

Vestavěné třídy: Object, Array, Function, Date, RegExp, Error.

Rovnost

 * Použijte operátory přísné rovnosti ( a  ) místo (volné) rovnosti (  a  ). Ten druhý dělá typ nátlaku.
 * Nepoužívejte Yodovy podmínky.



Kontroly typů

 * string:
 * number:
 * boolean:
 * Function:
 * null:
 * object:
 * Plain Object:
 * Array:
 * HTMLElement:
 * undefined:
 * Místní proměnné:
 * Vlastnosti:
 * Globální proměnné

Řetězce
Pro řetězcové literály používejte jednoduché uvozovky místo dvojitých. Pamatujte, že v JavaScriptu nejsou žádné "kouzelné uvozovky", tj.  a   fungují všude.

Chcete-li extrahovat část řetězce, použijte pro konzistenci metodu. Vyhněte se metodám  nebo , které jsou nadbytečné, snadno zaměnitelné a mohou mít neočekávané vedlejší účinky.

Export
Použijte globální hodnoty vystavené prohlížečem (například document, location, navigator) přímo a ne jako vlastnosti objektu window. To zvyšuje důvěru v kód prostřednictvím statické analýzy a může také umožňovat další funkce IDE. Kromě globálů prohlížeče jsou bezpečné k použití pouze,   a.

Vyhněte se vytváření nových globálních proměnných. Vyhněte se úpravám globálních prvků, které "nevlastní" váš kód. Například vestavěné globály, jako je String nebo Object, nesmí být rozšířeny o další obslužné metody a podobně by těmto globálům neměly být přiřazeny funkce související s OOjs nebo jQuery.

Chcete-li veřejně vystavit funkce pro opětovné použití, použijte  ze  anebo přiřaďte vlastnosti v rámci hierarchie , např. .

Všimněte si, že konfigurační proměnné vystavené MediaWiki musí být přístupné přes.

Prostředí
Úprava vestavěných prototypů, jako je, je považována za škodlivou. Toto není podporováno v kódu MediaWiki a pravděpodobně to povede k poškození nesouvisejících funkcí.

Pojmenovávání
Všechny proměnné musí být pojmenovány pomocí CamelCase začínající malým písmenem, nebo pokud proměnná představuje nějaký druh konstantní hodnoty, použijte velká písmena (s podtržítky pro oddělení).

Všechny funkce musí být pojmenovány pomocí CamelCase, obvykle začínající malým písmenem, pokud není funkce konstruktorem třídy, v takovém případě musí začínat velkým písmenem. Funkce Metod jsou preferovány se začátečním slovesem, např. místo.

Zkratky
Jména, která obsahují zkratky, by měla zkratku považovat za normální slovo a podle potřeby používat pouze velké první písmeno. To platí i pro dvoupísmenné zkratky, například. Například  na rozdíl od "getHTMLAPISource".

jQuery
Odlište uzly DOM od objektů jQuery předponou proměnným znakem dolaru, pokud budou obsahovat objekt jQuery, např. . To pomáhá omezit chyby tam, kde podmínky používají nesprávné podmíněné kontroly, jako je  namísto. Tam, kde metody DOM často vracejí hodnotu null (což je nepravda), metody jQuery vracejí prázdný objekt kolekce (které jsou, stejně jako nativní pole a další objekty v JavaScriptu, pravdivé).

npm
Při publikování samostatného projektu na npmjs.org zvažte jeho publikování pod jmenným prostorem. Všimněte si, že některé samostatné projekty, které jsou zaměřeny na použití mimo komunitu Wikimedia a mají dostatečně jedinečný název, v současnosti používají název balíčku bez jmenných prostorů (např. "oojs" a "visualeditor"). T239742



Vytváření prvků
Chcete-li vytvořit prostý prvek, použijte jednoduchou syntaxi v konstruktoru jQuery:

Při vytváření prvků na základě názvu značky z proměnné (která může obsahovat libovolný html):

Only use when you need to parse HTML (as opposed to creating a plain element).

Sbírky
Různé typy kolekcí někdy vypadají podobně, ale mají odlišné chování a mělo by se s nimi tak zacházet. Tento zmatek je většinou způsoben tím, že pole v JavaScriptu vypadají hodně jako pole v jiných jazycích, ale ve skutečnosti jsou pouze rozšířením Object. Používáme následující konvence:

Nepoužívejte smyčku  k opakování přes pole (na rozdíl od prostého objektu), protože   bude mít za následek mnoho neočekávaných chování, včetně: Klíčů jako řetězců, nestabilního pořadí iterací, indexů může přeskakovat mezery, opakování může zahrnovat jiné nečíselné znaky vlastnosti.

Úložiště
Klíče v localStorage anebo sessionStorage by měly být přístupné přes  nebo.

Klíče
Keys by měl začínat  a používat Camel Case anebo spojovníky. Nepoužívejte podtržítka ani jiné oddělovače. Příklady skutečných klíčů:



Dejte si pozor na to, že na rozdíl od souborů cookie přes mw.cookie není ve výchozím nastavení přidána žádná wiki předpona nebo předpona cookie. Pokud se hodnoty musí lišit podle wiki, musíte ručně zahrnout  jako součást klíče.

Hodnoty
Hodnoty musí být řetězce. Pozor, pokus o uložení jiných typů hodnot se tiše přetypuje na řetězec (např. z se stane ).

Prostor je omezený. Kde je to možné, používejte krátké a výstižné hodnoty před objektovými strukturami. Několik příkladů:


 * Pro booleovský stav (pravda/nepravda, rozbaleno/sbaleno) použijte "1" nebo "0".
 * Hodnoty, které jsou vždy čísly, je uložte tak, jak jsou, a na cestě ven přetypujte s  (vyhněte se  ).
 * Hodnoty, které jsou vždy řetězce, uložte tak, jak jsou.
 * U seznamů softwarově definovaných hodnot zvažte řetězce oddělené čárkami nebo svislou čarou, abyste snížili prostor a náklady na zpracování.
 * Pro seznamy hodnot, které mohou být vytvořeny uživatelem nebo jsou jinak složité povahy, použijte JSON.



Strategie vylučování
Pamatujte, že místní úložiště nemá ve výchozím nastavení žádnou strategii vylučování. Proto je třeba se vyhnout následujícímu:


 * Nepoužívejte jako součást názvu klíče vstup generovaný uživatelem.
 * Vyhněte se klíčům obsahujícím identifikátory entit generovaných uživateli (např. uživatelská jména, názvy kategorií, ID stránek nebo jiné proměnné poskytnuté uživatelem nebo systémem).
 * Obecně se vyhněte přístupům, které zahrnují vytváření potenciálně velkého počtu klíčů úložiště.

Pokud například funkce potřebuje uložit stav proměnné entity (např. aktuální stránky), může mít smysl použít jeden klíč pro tuto funkci jako celek a omezit uložené informace pouze na několik posledních iterací (LRU). . Mírné zvýšení nákladů na vyhledání (celý klíč namísto samostatných menších) se považuje za vhodné, protože jinak by počet klíčů nekontrolovatelně rostl.

I když klíče nezávisí na vstupu uživatele, možná budete chtít pro svou funkci použít jeden klíč, protože jinak budou mít předchozí verze vašeho softwaru uložená data, která nebudete moci vyčistit. Použitím jediného klíče jej můžete přepínat způsobem, který přirozeně nepřetrvává neznámé dílčí vlastnosti.

Použití sledovacího klíče je také anti-vzor a nevyhne se výše uvedeným problémům, protože by mohlo dojít k úniku kvůli závodním podmínkám ve webovém úložišti HTML5, které je sdíleno a není atomické mezi více otevřenými kartami prohlížeče.

Když má být funkce místního úložiště odstraněna, nezapomeňte nejprve implementovat strategii vystěhování, abyste odstranili staré hodnoty. Obvykle se mw.requestIdleCallback používá k elegantnímu vyhledání klíče a jeho odstranění. Viz T121646 pro škálovatelnější přístup.



Osobní údaje
Neukládejte do místního úložiště osobní údaje, které zůstanou, když se uživatel odhlásí nebo zavře prohlížeč. Použijte místo toho úložiště relací. Podívejte se na stránku T179752.



Asynchronní kód
Asynchronní kód by se měl řídit standardem Promise a být s ním kompatibilní.

Když definujete asynchronní metodu pro volání jiného kódu, můžete interně zkonstruovat vrácený objekt potom pomocí $.Deferred nebo nativní Promise. Nezapomeňte se spoléhat na polyfill v, pokud používáte Promise (tato polyfill je automaticky přeskočena a vyloučena z vašeho balíčku modulů v moderních prohlížečích).

Když zavoláte asynchronní metodu, použijte pouze standardní metody kompatibilní s Promise, jako jsou  a. Vyhněte se používání metod specifických pro jQuery, jako je  nebo , které by mohly přestat fungovat bez varování, pokud metoda, kterou voláte, interně přejde z $.Deferred na nativní Promise.

Všimněte si, že ve zpětných voláních  a   existují také jemné starší chování. Při migraci stávajícího kódu z  na   věnujte zvýšenou pozornost, protože to může způsobit, že kód přestane správně fungovat. Konkrétně, zpětná volání  a   vyvolají vaše zpětné volání synchronně, pokud bylo odložené volání již vyřízeno v době, kdy připojíte zpětné volání. To znamená, že vaše zpětné volání může být vyvoláno před dokončením příkazu připojení.

Například:



Závěrečné poznámky


Opětovné použití modulů ResourceLoader
Don't reinvent the wheel. Much JavaScript functionality and MediaWiki-related utilities ship with MediaWiki core that are stable and you can (literally) depend on them. See before rolling your own code.

Úskalí
Read more:
 * Be careful to preserve compatibility with left-to-right and right-to-left languages (i.e.  or  ), especially when styling text containers. Putting those declarations in CSS file will allow them to be automatically flipped for RTL-languages by  in.
 * Use  and   appropriately.
 * jQuery#attr, jQuery API
 * Attributes and custom properties, javascript.info
 * Consistently quote attribute selector values:  instead of   (jqbug 8229).
 * As of jQuery 1.4 the jQuery constructor has a new feature that allows passing an object as second argument, like . Don't use this. It makes code harder to follow, fails on attributes (such as 'size') that are also methods, and is unstable due to this mixing of jQuery methods with element attributes. A future jQuery method or plugin called "title" might convert an element into a heading, which means the title attribute can also no longer be set through this method. Be explicit and call ,  ,   etc. directly.



Použijte CSS pro úpravu stylů mnoha prvků
Neaplikujte styl na mnoho prvků najednou. Oslabuje to výkon. Místo toho použijte společnou rodičovskou třídu (nebo jednu přidejte) a použijte CSS v souboru  nebo. Díky ResourceLoaderu se to vše načte ve stejném požadavku HTTP, takže za samostatný soubor CSS nedochází k žádnému snížení výkonu. Nenastavujte CSS do inline atributů "style", nevkládejte ani prvky "style" z JS.

Poznámky pod čarou

 * JavaScript Style Guide, Contribute to jQuery
 * Code Conventions for JavaScript, Douglas Crockford
 * Programming Style & Your Brain, Douglas Crockford on YouTube