PHP 8.6 vychází 19. listopadu. DressCode pro něj kód přepisuje už teď. 16 dní Přechod na novější PHP →
EN Začít

Formátování kódu krok za krokem

Váš projekt už svůj styl kódu dávno má, i když ho možná nikdo formálně nesepsal. DressCode mu vezme míru přesně na tělo, promítne ji do konfigurace a první automatickou opravu udrží v bezpečném rozsahu několika málo souborů. Těchto šest kroků vás spolehlivě dovede od prvního spuštění dresscode init až k přirozenému standardu, který za vás bude neúnavně hlídat CI, Git hook, editor i AI agent – a který můžete kdykoliv snadno zpřísnit.

Pokud DressCode ještě nemáte nainstalovaný nebo si ho chcete jen nanečisto vyzkoušet, návod Začínáme s DressCode vám zabere pět minut. Kompletní přehled voleb pro příkazy init, check, fix a baseline najdete v referenci příkazové řádky.

1. Změřte, co váš kód už dodržuje

Běžný postup při zavádění coding standardu vypadá tak, že si tým vybere nějaký standard zvenčí, spustí formátovač a dostane gigantický diff, který překope polovinu projektu. Takovou změnu nikdo v code review reálně nezkontroluje a otevřené větve okamžitě spadnou do nepříjemných konfliktů. DressCode na to jde z opačného konce a vychází z kódu, který už máte. V kořeni projektu jednoduše spusťte:

dresscode init

Příkaz init otestuje váš kód proti všem dostupným standardům a vybere ten, se kterým by oprava zasáhla nejmenší počet souborů. Následně detailně proměří rozhodnutí, v nichž se váš kód od tohoto standardu odchyluje, a uloží je s hodnotami, které v projektu reálně převažují. Výstup v terminálu přesně popíše, co zjistil:

Standard   perCs (PER Coding Style), the nearest to your code by the files a fix changes, 13 under psr12; `--use` names another
Measured   your code departs from it in 3 decisions over 13 files; perCs as it is, with no decision below `use`, would rewrite 13 of them
As written indentation.unit: tab   your code, 92% of 13 files
           blankLines.beforeDeclaration: 2   your code, all 13 places
           braces.emptyBody.function: expanded   your code, all 26 places
Checked    all 13 files: a fix changes 1 file, 1 of them for the indentation, the line endings or the long lines the rest of the code has
...
Written    `dresscode.neon`

V této ukázce je nejbližším standardem perCs, tedy PER Coding Style 3.1. Všimněte si řádku Measured: v čisté podobě by standard přepsal všech 13 souborů. Jakmile se však přidají tři rozhodnutí odvozená z vašeho kódu, změní oprava podle řádku Checked jediný soubor. V tom spočívá celá pointa: základní kostru dodá standard, odchylky si určí váš kód a každá hodnota transparentně uvádí, o co se opírá (your code, 92% of 13 files).

I tak se může starší projekt od nejbližšího standardu lišit na spoustě míst – a první oprava rozhodně nemá převrátit půlku repozitáře vzhůru nohama. Proto init hlídá rozpočet změn: automatická oprava smí ve výchozím nastavení změnit nejvýše 1 % souborů (minimálně 2 a maximálně 20; jiný limit určí přepínač --budget). Výjimkou je pouze odsazení, délka řádků a konce řádků – ty se srovnají bez ohledu na rozpočet, protože na nich stojí všechno ostatní (soubory, kterých se to týká, počítá řádek Checked zvlášť). Kdyby měly opravy rozpočet překročit, nechá init sporná rozhodnutí zatím neaktivní a v interaktivním průvodci se vás na ně zeptá i s ukázkou konkrétního místa v kódu. Stejně tak se zeptá, pokud jsou dva standardy v těsném souboji. Doporučená odpověď je vždy na prvním místě a stačí ji potvrdit klávesou Enter. Tato volba ponechá kód v původním stavu, takže ani při nejistotě nic nerozbijete.

Mimo interaktivní terminál (nebo s přepínačem --yes) se init na nic neptá a rovnou zvolí doporučené odpovědi. Každou otázku pak vypíše na řádku Your call s hotovým zápisem pro dresscode.neon nebo s příkazem, kterým můžete volbu změnit. Chcete-li kód měřit podle konkrétního standardu, stačí jej zadat: dresscode init --use nette. Pokud projekt už využívá PHP_CodeSniffer, PHP CS Fixer nebo Laravel Pint, init načte i jejich existující pravidla (postup přímého překladu pravidel popisuje stránka Přechod na DressCode). Všechny podrobnosti najdete v popisu příkazu init.

2. Projděte a upravte konfiguraci

Příkaz init vytvořil v kořeni projektu soubor dresscode.neon. Pokud pomineme vyloučené cesty a zjištěné deklarace z namespace, vypadá jeho struktura takto:

# made to measure by `dresscode init`; run it again to see what has moved since, it writes nothing over this file
use: perCs   # PER Coding Style, of the standards the one a fix changes the fewest files of your code under

paths: [src, tests]

indentation:
	unit: tab                # your code, 92% of 13 files

braces:
	emptyBody:
		function: expanded   # your code, all 26 places

blankLines:
	beforeDeclaration: 2     # your code, all 13 places

Soubor dává jasnou odpověď na dvě otázky. Klíč use určuje základní styl: jmenuje vybraný standard a za něj můžete připojit sady (například cleanup), které od kódu žádají více než pouhý vzhled. Klíče pod ním pak položku po položce říkají, v čem se váš projekt od standardu odchyluje. O čem soubor výslovně nemluví, to přebírá hodnotu ze standardu.

Každý klíč představuje přesnou cestu rozhodnutí – tutéž, kterou vidíte u každé chyby ve výpisu terminálu. Pokud vám některý parametr není jasný, nechte si jej osvětlit: příkaz dresscode explain braces.emptyBody.function vypíše, k čemu rozhodnutí slouží, jaké hodnoty přijímá, jak je nastavené ve vašem projektu a co k němu říkají zavedené standardy. Příkaz dresscode config vám zase ukáže kompletní vyřešenou konfiguraci se všemi aktivními pravidly a jejich původem.

Kteroukoliv hodnotu můžete kdykoliv upravit, nebo řádek smazat a nechat rozhodnutí na standardu. Než konfiguraci upravíte natrvalo, vyzkoušejte si změnu nanečisto na jeden běh: dresscode check --set literals.quotes=single --only literals.quotes --diff vám v diffu ukáže, co by přineslo vynucení jednoduchých uvozovek, aniž by cokoliv zapsal na disk. Hodnota keep znamená „nekontrolovat“ a dané rozhodnutí zcela vypne, i kdyby ho standard přímo vyžadoval. Všechny možnosti zápisu podrobně rozebírá stránka Konfigurace.

3. První oprava jako samostatný commit

Před spuštěním první automatické opravy si commitněte rozdělanou práci, nebo mějte čistý pracovní strom v Gitu, aby diff ukázal čistě jen změny provedené DressCode. Poté se podívejte na plánované úpravy a nechte nástroj pracovat:

dresscode check --diff
dresscode fix

Příkaz check --diff přehledně zobrazí změny bez zápisu, zatímco fix soubory reálně upraví. Každý změněný soubor nese ve výpisu označení rewritten. Pod ním zůstanou pouze věci, které automaticky vyřešit nelze – například nekonvenční název metody, který by bylo nutné přejmenovat i na všech místech jejího volání v projektu.

Výsledek commitněte společně s vygenerovaným dresscode.neon, který změny vysvětluje, a bez jakýchkoliv jiných úprav kódu. Takový commit nemusí v týmu nikdo luštit řádek po řádku – stačí vědět, že obsahuje výhradně formátování. git blame pak u přeformátovaných řádků spolehlivě odkáže na tento formátovací commit, a nikoliv na váš následující věcný commit s byznysovou logikou. Díky rozpočtu zůstane první commit příjemně malý, takže se jen zřídka dostane do konfliktu s otevřenými větvemi kolegů. Pokud jste rozpočet záměrně zvedli nebo měníte více pravidel najednou, rozdělte úklid do několika samostatných commitů podle sad či sekcí (více na stránce Uklidit starý kód po krocích).

4. Co žádné pravidlo neopraví

I po automatické opravě může check hlásit několik míst, která vyžadují zásah vývojáře: metodu get_total, jež má být správně v camelCase, rizikovou opravu (risky fix), kterou projekt zatím nepovolil, nebo řádek přesahující limit file.lineLength, který DressCode neumí bezpečně sám zalomit. Z takové situace vedou tři přímočaré cesty:

Pokud jde o pár ojedinělých míst, upravte je ručně. Pokud pravidlo na daném místě zkrátka nemá pravdu, potlačte jej přímo v kódu komentářem // dresscode:ignore naming.method a za dvě pomlčky připište důvod. A pokud má pravidlo pravdu, ale dnes nemáte čas stovky starých míst přepisovat, uložte zbytek chyb do baseline:

dresscode baseline

Baseline with 312 violations written to `dresscode-baseline.neon`.

Od této chvíle se budou hlásit už pouze nově vzniklá porušení. Baseline eviduje výhradně to, co po sobě zanechá automatický fix, a proto ji generujte až po jeho spuštění. Kdyby totiž oprava mohla ještě cokoliv změnit, příkaz baseline nezapíše nic a vyzve vás, abyste nejprve pustili fix. Rozdíl mezi potlačením a baseline je zásadní: potlačení (suppression) říká „tady pravidlo neplatí“ a zastaví i případnou automatickou opravu, kdežto baseline říká „toto zatím neumíme vyřešit“, opravám nikdy nebrání a postupně má ubývat. Jakmile z kódu některá chyba zmizí, běh vás na zastaralý záznam v baseline sám upozorní. Všechny úrovně potlačení i práci s baseline podrobně popisuje stránka Potlačení a baseline.

5. Ať to tak zůstane

Coding standard, který stojí na tom, že si na něj někdo před commitem vzpomene, časem nevyhnutelně vybledne. Nechte jeho hlídání na nástrojích, které už používáte:

  • Průběžná integrace (CI) spustí dresscode check při každém pushi; jakmile kód cokoliv poruší, job skončí s exit kódem 1 a selže. Na GitHub Actions se jednotlivé nálezy zobrazí formou přehledných anotací přímo u příslušných řádků v pull requestu (viz Průběžná integrace).
  • Git hook bleskově zkontroluje pouze soubory připravené ke commitu (staged), a dokud je vše v pořádku, nezdržuje žádným výpisem (viz Git hooky).
  • Editor soubor automaticky zformátuje při každém uložení pomocí dresscode fix --stdin. Funguje to v PhpStormu, ve VS Code i v jakémkoliv jiném editoru s podporou formátování přes standardní vstup (viz Editory a IDE).
  • AI agent s pluginem php-fixer v Claude Code či Codexu dostane každý soubor, který upraví, okamžitě učesaný podle vaší konfigurace a přesně ví, co se v něm změnilo (viz AI agenti).

Všechny tyto nástroje čtou jeden a týž soubor dresscode.neon. Server, Git hook, vývojářský editor i AI agent tak drží kód v naprosto shodném stylu. Čím začít, poradí stránka Integrace.

6. Časem zpřísněte

Konfigurace, kterou init vytvořil, věrně odráží stav vašeho kódu v daný den – včetně všech historických kompromisů. Rozhodnutí, která odložil rozpočet, zůstávají v souboru poznamenaná jako keep s komentářem not checked: a fix would change … a přesným počtem dotčených souborů. Jakmile na ně budete mít prostor, vyzkoušejte si je a začleňte je do samostatného commitu:

dresscode check --set literals.quotes=single --only literals.quotes --diff
dresscode fix --set literals.quotes=single

První příkaz vám v diffu ukáže plánované úpravy bez zápisu na disk. Druhý spustí celou konfiguraci rozšířenou o toto jedno pravidlo, takže provedené změny vyjdou rovnou zformátované přesně podle vašeho standardu. Pak stačí hodnotu zapsat do dresscode.neon namísto původního keep a obojí najednou commitnout (viz Zavést nové rozhodnutí jedním commitem).

Stejně můžete naložit i s hodnotami, které init naměřil z vašeho kódu. Tyto hodnoty často představují pozůstatek starších zvyklostí, zatímco standard se mezitím posunul kupředu. Chcete-li jít s ním, smažte příslušný řádek z dresscode.neon a spusťte fix. U celých sad je postup stejný: příkaz dresscode check --use cleanup --diff vám přehledně ukáže dopad sady cleanup dříve, než ji natrvalo přidáte do klíče use.

Po aktualizaci DressCode nebo po několika měsících aktivního vývoje spusťte dresscode init znovu. Existující konfiguraci nepřepíše. Znovu proměří celý projekt a přehledně vypíše každé rozhodnutí, které by dnes nastavil jinak, včetně počtu souborů, jež by oprava změnila. Upozorní i na pravidla, která máte v souboru nastavena odlišně od standardu, přestože váš kód se standardu mezitím začal sám držet. Pokud se nic neposunulo, výpis vás ujistí, že vše sedí:

Compared   the code with the standard and the decisions of `dresscode.neon`, over the files it checks
Moved      nothing: `dresscode.neon` says what init measures

`dresscode.neon` exists, so nothing is written; `dresscode check --set path=value` shows what a value would change.

Kam dál

Zobrazit na GitHubu · Nahlásit problém se stránkou na GitHubu · 2. 11. 2026