Manual:Coding conventions/cs

Tato stránka popisuje konvence pro psaní kódu se kterým pracuje MediaWiki a její rozšíření, s nimiž se můžete setkat na webových stránkách projektů Wikimedie. Včetně konvence pro tvorbu jmen. Úpravám, které nebudou v souladu s touto konvencí, revidenti kódu dají v hodnocení -1; což lze automaticky brát jako výzvu k tomu, aby byl kód opraven tak, aby byl v souladu s touto konvencí a oprava byla aktualizována.

Tato stránka popisuje všeobecnou konvenci pro psaní kódu, která se týká veškerého kódu MediaWiki, bez ohledu na programovací jazyk. Pro další pokyny, které se týkají konkrétních komponent či typů souborů v MediaWiki, viz:



Na wikitech (platí alespoň pro operace / puppet):


 * Puppet

Odsazení
Řádky mohou být odsazeny znakem tabulátor (tab), pro každou úroveň zanoření. Pokud jde o velikost odsazení tabulátoru co do počtu mezer, tak většina vývojářů MediaWiki používá u svých editorů pro interpretaci tabulátoru 4 mezery, což je optimální pro čtení, ale řada systémů předpokládá, že má tabulátor o velikosti 8 mezer a někteří vývojáři zase pro změnu používají tabulátory o velikosti pouhé 2 mezery.

Uživatelé editoru vim si mohou velikost tabulátoru nastavit tak, že přidají do $HOME/.vimrc následující kód:

autocmd Filetype php setlocal ts=4 sw=4

řádky s nastavením pro CSS, HTML a JavaScript vypadají podobně.

Nicméně v případě Pythonu je podle PEP 8 lepší používat místo tabulátoru mezery.

Konce řádků
Všechny soubory by měly používat unixové konce řádků, t.j. jeden znak LF (line feed - zalomení řádku). Tedy žádnou kombinaci znaků CR (carriage return - návrat vozíku) + LF.


 * git v prostředí Windows (by default) převádí znaky CR+LF (které označují konce řádku v prostředí tohoto systému) na LF při ukládání změn (commit).

Všechny soubory by měly končit prázdným řádkem.


 * Protože je logické, aby všechny řádky končily stejně – znakem zalomení řádku.
 * Jednotné zakončení řádku usnadňuje také předávání dat v jiných než binárních formátech (např. formou rozdílových souborů generovaných přes diff).
 * Pokud se vyskytují v souborech různé typy konce řádku, tak nástroje pro příkazovou řádku, jako např. cat nebo wc nefungují tak, jak by měly.

Kódování
Všechny texty musí být v UTF-8 bez znaku BOM.

Nepoužívejte k editaci souborů Microsoft Notepad, protože ten do nich vždy nacpe BOM. BOM je speciální znak na začátku souboru, na kterém PHP přeruší další zpracování souboru, takže se do webového prohlížeče na straně klienta dostane pouze tento znak.

Stručně řečeno, ujistěte se, že váš editor podporuje UTF-8 bez BOM.

Mezery na konci řádku
Když používáte IDE, stisknutím kláves Domů a Konec (mimo jiné klávesové zkratky) obvykle ignorujete koncové mezery a místo toho přeskočíte na konec určeného kódu. V textových editorech jiných než IDE však stisknutí tlačítka End přeskočí na úplný konec řádku, což znamená, že vývojář musí použít backspace přes koncové mezery, aby se dostal na místo, kam chce skutečně psát.

Odstranění koncové mezery je ve většině textových editorů triviální. Vývojáři by neměli přidávat koncové mezery, zejména ne na řádcích, které obsahují jiný viditelný kód.

Některé nástroje to usnadňují:


 * nano: GNU nano 3.2;
 * : v nabídce Možnosti uložení z nabídky „Úpravy> Předvolby“ povolte „Vymazat koncové mezery a značky EOL“ (Clean trailing whitespace and EOL markers) a „Pouze vyčistit změněné řádky“ (Only clean changed lines);
 * Kate: koncové mezery můžete vidět povolením možnosti „Zvýraznit koncové mezery“. Tuto možnost najdete v části „Nastavení > Konfigurovat Kate > Vzhled“. Můžete také zadat Kate, aby vyčistila koncové mezery při uložení v „Nastavení > Konfigurovat Kate> Otevřít nebo Uložit“.
 * vim: různé pluginy pro automatické čištění;
 * Sublime Text: TrailingSpaces plugin.

Klíčová slova
Nepoužívejte závorky s klíčovými slovy (jako např.,  ), pokud to není nezbytně nutné.

Obecný styl
Styl odsazení MediaWiki je podobný tzv. „One True Brace Style“. Zarážky jsou umístěny na stejném řádku jako začátek funkce, podmínka, smyčka atd. Jinak nebo jinde je umístěn na stejném řádku jako předchozí zavírací zarážka.

Víceřádkové příkazy se zapisují tak, že druhý a následující řádky jsou odsazeny o jednu úroveň navíc:

Použijte odsazení a konce řádků ke zvýraznění logické struktury vašeho kódu. Výrazy, které se vnořují do více úrovní závorek nebo podobných struktur, mohou začít novou úroveň odsazením s každou úrovní vnoření:

V příkazech pro přepínání odsazení v závorkách a mezi případy:

Vertikální zarovnání
Vyvarujte se vertikálního zarovnání pomocí tabulátorů. Má tendenci vytvářet rozdíly, které je obtížné interpretovat. Šířka povolená pro levý sloupec musí být neustále zvyšována, jakmile se přidává více položek.

Pokud potřebujete, použijte pro vertikální zarovnání položek raději mezery, než tabulátory. Zarovnání jako u tohoto příkladu:

Dosáhnete toho takto (mezery jsou vykresleny jako tečky):

 $namespaceNames·=·[ → NS_MEDIA············=>·'Media', → NS_SPECIAL··········=>·'Special', → NS_MAIN·············=>·'', ]; (Pokud používáte doplněk tabular vim add-on, zadáním :Tabularize /= zarovnáte znaky '='.)

Zalomení řádků
Řádky by měly být zalomeny mezi 80 a 100 sloupcem. Z tohoto pravidla existují vzácné výjimky. Ale funkce, kterým se předává hodně parametrů, mezi ně rozhodně nepatří.

Operátor který je rozdělen na dva řádky byste měli umisťovat pokud možno konzistentně (pokaždé buď na konci řádku, nebo naopak pokaždé na začátku řádku). I když některé jazyky pro to mohou mít svá vlastní, specifická pravidla.

Operátor metody by vždycky měl být umístěn na začátku dalšího řádku.

Pokud pokračujete v příkazech „if“, přepnutí na složené závorky Allman-style jasně stanoví oddělení mezi podmínkou a tělem:

Názory se liší v rozsahu odsazení, které by mělo být použito pro podmíněnou část. Použití množství odsazení odlišného od toho, které používá tělo, objasňuje, že podmíněná část není tělem, ale toto není všeobecně podporováno.

Pokračování podmíněných a velmi dlouhých výrazů bývá ošklivé, ať už je děláte jakýmkoli způsobem. Proto je někdy nejlepší je rozdělit pomocí dočasných proměnných.

Závorky diktují strukturu
I když se vám to může zdát efektivnější, vyvarujte se u podmínek a funkcí psaní jednořádkových "bloků" kódu. Zhoršuje to přehlednost kódu. Důležité příkazy se tím dostávají na pozice, kde je lze při čtení kódu snadno přehlédnout. Uvědomte si, že cílem není získat naňahňaný minimalistický kód. Při psaní kódu byste měli především brát ohled na to, abyste v maximální míře usnadnili čtení kódu, tak aby mu porozuměli i ostatní vývojáři.

Tím se zabrání běžné logické chybě, která je zvláště rozšířená, když vývojář používá textový editor, který nemá funkci „inteligentního odsazení“. K chybě dochází, když je jednořádkový blok později rozšířen na dva řádky:

Později změněno na:

To má potenciál vytvářet jemné chyby.

emacs styl
V emacs pomocí  od nXHTML mode, můžete nastavit menší režim MediaWiki v souboru .emacs:

Výše uvedená funkce  zkontroluje vaši cestu, když je vyvolán , aby zjistil, zda obsahuje „mw“ nebo „mediawiki“ a nastaví vyrovnávací paměť pro použití menšího režimu   pro úpravu zdroje MediaWiki. Že se vyrovnávací paměť  používá poznáte, protože v řádku režimu uvidíte něco jako „PHP MW“ nebo „PHP / lw MW“.

Vytváření adres URL
Nikdy nevytvářejte adresy URL ručně s řetězcovým zřetězením nebo podobným způsobem. Pro požadavky zadané vaším kódem vždy používejte plný formát URL (zejména POST a požadavky na pozadí).

V PHP můžete použít příslušnou metodu nebo, magické slovo  ve wikitextu, mw.util.getURL metoda v JavaScriptu a podobné metody v jiných jazycích. Vyhnete se tak problémům s neočekávanou krátkou konfigurací URL a dalším.

Pojmenování souboru
Soubory, které obsahují kód na straně serveru, by měly být pojmenovány v UpperCamelCase. Toto je také naše konvence pojmenování pro rozšíření. Pojmenujte soubor po nejdůležitější třídě. Většina souborů bude obsahovat pouze jednu třídu nebo základní třídu a řadu potomků. Například  obsahuje pouze třídu  ;   obsahuje třídu   a také její potomky   a.

Přístupové soubory
Pojmenujte soubory „přístupového bodu“, například SQL, a vstupní body PHP, například  a   v lowercase. Skripty pro údržbu jsou obvykle v lowerCamelCase i když se to poněkud liší. Soubory určené pro správce webu, jako jsou readmes, licence a changelogs, jsou obvykle v UPPERCASE.

Nikdy nezahrnujte mezery do názvů souborů nebo adresářů a nikdy nepoužívejte znaky jiné než ASCII. U titulů s malými písmeny jsou spojovníky upřednostňovány před podtržítky.

JS, CSS a mediální soubory
U souborů JavaScript, CSS a mediálních souborů (obvykle načtených pomocí ResourceLoader) by se pojmenování souborů mělo shodovat s pojmenováním modulů. Například:
 * Modul  může obsahovat soubory   a
 * modul  obsahuje soubor

Názvy modulů zaregistrovaných pomocí rozšíření by měly následovat název jako, například:

Díky tomu je snadné najít soubory, i když modul rozdělíte na menší soubory, abyste je mohli pohodlně upravovat, a pak je spojíte do jednoho modulu.

Dokumentace
Dílčí stránky specifické pro jazyk mají více informací o přesné syntaxi kódových komentářů v souborech, např. komentáře v PHP pro doxygen. Použití přesné syntaxe nám umožňuje generovat dokumentaci ze zdrojového kódu na adrese http://doc.wikimedia.org.

Některé prvky MediaWiki jsou dokumentovány v základní složce. Pokud například přidáte nový háček, měli byste aktualizovat s názvem háčku, popisem toho, co háček dělá a parametry používanými háčkem.

Textové soubory
Vývojáři mohou uchovávat soubory dokumentace v Gitu vedle kódu. Může to být užitečné pro podrobnou dokumentaci architektury rozšíření, návrhu databáze atd., kterou byste měli aktualizovat s každým kódem, který změní chování. Stránky na mediawiki.org, které se týkají dokumentace v Gitu, by na ni měly odkazovat pomocí.

(Možnost převést text ze souborů Git na stránky wiki je sledována v T91626.)

Mnoho stránek technické dokumentace na stránkách mediawiki.org dokumentuje vývoj kódu MediaWiki v mnoha vydáních. Popište změny v dokumentu nebo uveďte, že popisuje pouze poslední kódovou základnu v „master“.

Formáty textových souborů

 * Pokud je váš textový soubor wikitext, zadejte příponu . GitHub umí analyzovat podmnožinu wikitextu, takže   soubory zrcadlené na GitHubu budou zobrazovat určité formátování (rozšíření   také funguje, ale je delší) . Například   rozšíření Wikibase v GitHub.
 * Pokud je váš textový soubor wikitext, zadejte příponu . GitHub umí analyzovat podmnožinu wikitextu, takže   soubory zrcadlené na GitHubu budou zobrazovat určité formátování (rozšíření   také funguje, ale je delší) . Například   rozšíření Wikibase v GitHub.


 * Doxygen podporuje formátování Markdown, takže můžete do souborů  vkládat lehce formátovanou dokumentaci. Diffusion a GitHub také podporují soubory  . Název vysvětlujícího souboru pro adresář nebo projekt  . Aplikace Diffusion a GitHub zobrazí tento soubor při prohlížení tohoto adresáře nebo projektu (např. RESTbase , v  a na GitHub).
 * Doxygen podporuje formátování Markdown, takže můžete do souborů  vkládat lehce formátovanou dokumentaci. Diffusion a GitHub také podporují soubory  . Název vysvětlujícího souboru pro adresář nebo projekt  . Aplikace Diffusion a GitHub zobrazí tento soubor při prohlížení tohoto adresáře nebo projektu (např. RESTbase , v  a na GitHub).


 * bez přípony a
 * Doxygen je standardně analyzuje jako soubory jazyka C (!!, sledované v ). Toho můžete využít tak, že soubor napodobuje komentář C a poté do souboru přidáte doxygenové směrnice. Například vygeneruje Návrh backendového souboru v doxygenu a začíná:




 * Special:Version/Credits předpokládá, že  a   (bez přípony) jsou soubory wikitext.

Záhlaví zdrojových souborů
Aby bylo možné vyhovět většině licencí, měli byste mít v horní části každého zdrojového souboru něco podobného následujícímu (specifické pro aplikace GPLv2 PHP).

Licence
Licence se obecně označují celým svým jménem nebo zkratkou podle SPDX standard. Viz také Návod: $wgExtensionCredits#license.

Poznámky k vydání
Musíte dokumentovat všechny významné změny (včetně all fixed bug reports) do základního softwaru, který by mohl ovlivnit uživatele wiki, správce serverů, autory rozšíření v. se vyvíjí. Při každém vydání přesuneme předchozí poznámky k vydání do souboru  a začneme znovu. je obecně rozdělena do tří sekcí:


 * Configuration changes is the place to put changes to accepted default behavior, backwards-incompatible changes, or other things which need a server administrator to look at and decide "is this change right for my wiki?". Try to include a brief explanation of how the previous functionality can be recovered if desired.
 * Bug fixes is the place to note changes which fix behavior which is accepted to be problematic or undesirable. These will often be issues reported in Phabricator, but needn't necessarily.
 * New features is, unsurprisingly, to note the addition of new functionality.

There may be additional sections for specific components (e.g. the Action API) or for miscellaneous changes that don't fall into one of the above categories.

In all cases, if your change is in response to one or more issues reported in Phabricator, include the task ID(s) at the start of the entry. Add new entries in chronological order at the end of the section.

System messages
When creating a new system message, use hyphens (-) where possible instead of CamelCase or snake_case. So for example,  is a good name, while   and   are not.

If the message is going to be used as a label which can have a colon after it, don't hardcode the colon; instead, put the colon inside the message text. Some languages (such as French which require a space before) need to handle colons in a different way, which is impossible if the colon is hardcoded. The same holds for several other types of interpunctuation.

Try to use message keys "whole" in code, rather than building them on the fly; as this makes it easier to search for them in the codebase. For instance, the following shows how a search for  will not find this use of the message key if they are not used as a whole.

If you feel that you have to build messages on the fly, put a comment with all possible whole messages nearby:

See Localisation for more conventions about creating, using, documenting and maintaining message keys.

Preferred spelling
It is just as important to have consistent spelling in the UI and codebase as it is to have consistent UI. By long standing history, 'American English' is the preferred spelling for English language messages, comments, and documentation.

Abbreviations in message keys

 * ph
 * placeholder (text in input fields)


 * tip
 * tooltip text


 * tog-xx
 * toggle options in user preferences

Punctuation
Non-title error messages are considered as sentences and should have punctuation.

Improve the core
If you need some additional functionality from a MediaWiki core component (PHP class, JS module etc.), or you need a function that does something similar but slightly different, prefer to improve the core component. Avoid duplicating the code to an extension or elsewhere in core and modifying it there.

Refactoring
Refactor code as changes are made: don't let the code keep getting worse with each change.

However, use separate commits if the refactoring is large. See also Architecture guidelines (draft).

HTML
MediaWiki HTTP responses output HTML that can be generated by one of two sources. The MediaWiki PHP code is a trusted source for the user interface, it can output any arbitrary HTML. The Parser converts user-generated wikitext into HTML, this is an untrusted source. Complex HTML created by users via wikitext is often found in the "Template" namespace. HTML produced by the Parser is subject to sanitization before output.

Most data attributes are allowed to be used by users in wikitext and templates. But, the following prefixes have been restricted and are not allowed in wikitext. This enables client JavaScript code to determine whether a DOM element came from a trusted source:


 * – This attribute is present in HTML generated by OOUI widgets.
 * – reserved attribute for internal use by Parsoid.
 * and  – reserved attribute for internal use by MediaWiki core, skins and extensions. The   is also used by Parsoid.

When selecting elements in JavaScript, one can specify an attribute key/value to ensure only DOM elements from the intended trusted source are considered. Example: Only trigger 'wikipage.diff' hook for official diffs.