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.

Constructor dependency injection
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. For such new code, place all dependencies on the class constructor (or main entry point to the class) to easy migration to constructor dependency injection in the future.

File header
For new code, we have chosen the following minimalistic header:

If you wish to assert your copyright more explicitly, you can optionally add @copyright tag as well.

Deprecation and version numbers
When changing Translate code in backwards incompatible ways, do check https://codesearch.wmcloud.org/search/ for any users of the code. Known users are TwnMainPage, TranslateSVG, CentralNotice, MassMessage and bunch of stuff in the translatewiki repository.

You can use the deprecation facilities provided by MediaWiki core, including the @deprecated tag and wfDeprecated hard deprecation. If there are no known users of the code, it is okay to change it in backwards incompatible way without deprecation, unless it is explicitly marked as stable (See Stable interface policy). Code marked as stable should be hard-deprecated at least for one MLEB release.

MediaWiki core version numbers are meaningless in the context of Translate, as Translate always supports multiple MediaWiki releases. Translate itself uses YYYY.MM style versioning (as part of MLEB). New classes and methods should be annotated with @since YYYY.MM tags.