Help:Extension:Translate/Developer guide/cs

Rozšíření Translate je velké rozšíření se stovkami tříd. Tato stránka poskytuje pokyny pro vývojáře, kteří chtějí pracovat na kódu. Po přečtení této stránky a propojených dokumentů lépe pochopíte, jak je kód v Translate organizován a jaké speciální konvence se používají. Obecné zásady vývoje MediaWiki, konvence kódování a používání nástrojů jako Gerrit a Phabricator jsou mimo rozsah této statě. Předpokládá se, že tato témata znáte, a pokud se týkají Translate, nebudou se zde opakovat.

Rozšíření Translate prochází mnoha velkými migracemi současně. Zde uvádíme hlavní migrace, které právě probíhají, a podrobně popisujeme, který styl je preferován pro nový kód. Obecně platí, že při úpravách stávajícího kódu je lepší držet se aktuálního stylu a migrace provádět samostatně. Při osahávání kódu je v pořádku provést některá drobná čištění.

Migrace jmenného prostoru
Právě probíhá migrace veškerého kódu Translate pod jmenným prostorem. Veškerý jmenný kód je umístěn v adresáři. Všechny nové soubory PHP by měly být umístěny do vhodného jmenného prostoru. Informace o tom, které jmenné prostory budou k dispozici, najdete v. Jmenné prostory jsou organizovány podle domény, nikoli podle funkce. Ve jmenných prostorech a názvech tříd je potřebné se vyhnout zkratkám. Starší kód je v kořenovém adresáři úložiště a různých podadresářích.

Rozdělení testů na integrační a unit
Dříve se nerozlišovalo mezi integračními a unit testy. U nového kódu by hlavním typem testů měly být unit testy. Testy unit jsou umístěny v adresáři, který odpovídá rozložení jmenného prostoru. V tomto adresáři je Makefile pro snadné spuštění všech nebo částí testů unit během vývoje.

Typ prohlášení a komentáře
Každý nový kód by měl deklarovat parametry i návratové typy. Kromě toho by měly být povoleny přísné typy pomocí.

Díky deklaracím typů je nyní většina komentářů funkcí a metod nadbytečná, protože by pouze opakovaly názvy a typy parametrů. Z tohoto důvodu jsou linter (programátorský nástroj pro statickou analýzu kódu) kontroly na chybějící parametry nebo deklarace typu návratu zakázány pro kód pod  a , které zhruba korelují s místy pomocí deklarací typu. U tohoto kódu nepřidávejte nadbytečnou dokumentaci, pokud neposkytuje další hodnotu. Jedním takovým příkladem je poskytnutí přesnějších tipů pro typy polí, například:

Jak je znázorněno výše, pro komentáře, které mají pouze jednu značku nebo popis jednoho řádku, použijte také syntaxi komentáře s jedním řádkem.

Vkládání závislosti na konstruktoru
Nový kód by měl mít všechny své závislosti vložené pomocí konstruktoru. V některých případech to zatím není možné, protože některé služby jsou dostupné pouze v nejnovější verzi MediaWiki a také chybí podpora ObjectFactory pro některé typy tříd, jako jsou úlohy a skripty údržby. Pro takový nový kód umístěte všechny závislosti do konstruktoru třídy (nebo hlavní vstupní bod do třídy), abyste je v budoucnu snadno migrovali při vkládání závislostí konstruktoru.

Záhlaví souboru
Pro nový kód jsme zvolili následující minimalistickou hlavičku:

Pokud chcete svá autorská práva uplatnit explicitněji, můžete volitelně přidat také tag @copyright.

Změny a čísla verzí
Pokud Translate mění kód zpětně nekompatibilními způsoby, zkontrolujte https://codesearch.wmcloud.org/search/ pro všechny uživatele kódu. Známí uživatelé jsou TwnMainPage, TranslateSVG, CentralNotice, MassMessage a spousta věcí v úložišti translatewiki.

Můžete použít prostředky pro ukončení podpory poskytované jádrem MediaWiki, včetně značky @deprecated a tvrdého ukončení podpory wfDeprecated. Pokud nejsou známí uživatelé kódu, je v pořádku jej změnit zpětně nekompatibilním způsobem bez ukončení podpory, pokud není výslovně označen jako stabilní (viz Zásady stabilního rozhraní). Kód označený jako stabilní by měl být tvrdě zastaralý alespoň pro jedno vydání MLEB.

Čísla základních verzí MediaWiki nemají v kontextu Translate žádný význam, protože Translate vždy podporuje více vydání MediaWiki. Samotný Translate používá verzování ve stylu YYYY.MM (jako součást MLEB). Nové třídy a metody by měly být označeny značkami @since YYYY.MM.