Potlačení a baseline

Jak vypnout pravidlo na jednom řádku, v bloku nebo v celém souboru, proč potlačení zastaví i opravu, a jak nasadit DressCode na velký projekt bez obřího commitu díky baseline.

Čtyři úrovně

Výjimky z pravidel osobně nemám rád a v kódu je nepíšu; když už, tak v konfiguraci pro celou cestu. Ale jsou místa, kde pravidlo prostě nemá pravdu, a pak je dobré mít přesný nástroj a ne kladivo. DressCode má čtyři, od nejužšího po nejširší:

A vedle nich baseline, která není výjimka z pravidla, ale z času: zapíše porušení, která v projektu jsou dnes, a hlásí jen nová.

Ať zvolíte cokoli, platí jedna věc: potlačené porušení se neopraví. Pravidlo smí měnit kód jen poté, co ho ohlásilo a hlášení prošlo, a hlídá to engine, ne autor pravidla. Potlačení tedy není jen ticho ve výpisu, je to skutečné vypnutí.

Na řádku

Komentář dresscode:ignore na konci řádku potlačí porušení na tomto řádku. Bez jména potlačí všechna pravidla, se jménem jen to jedno; víc jmen oddělte čárkou:

$isEmpty = $value == null; // dresscode:ignore dresscode/strict-comparison

Komentář na vlastním řádku platí pro příkaz, který začíná na řádku pod ním, i když se ten příkaz táhne přes víc řádků:

// dresscode:ignore dresscode/multi-line-array
$matrix = [[1, 0, 0],
	[0, 1, 0],
	[0, 0, 1]];

Funguje //, # i /* */. Jméno pravidla je to z výpisu; místo něj DressCode přijme i jméno pravidla PHP CS Fixeru nebo PHP_CodeSniffer, které jeho pravidlo pokrývá, a stejně tak rozumí komentářům phpcs:ignore, phpcs:disable, phpcs:enable, phpcs:ignoreFile a anotaci @phpcsSuppress. Kdo přechází z jiného nástroje, nemusí do kódu sahat; přepis na nová jména udělá dresscode migrate-suppressions.

V bloku

// dresscode:disable dresscode/line-length
$data = ['alpha' => 1, 'beta' => 2, 'gamma' => 3, 'delta' => 4, 'epsilon' => 5, 'zeta' => 6, 'eta' => 7];
$more = ['theta' => 8, 'iota' => 9, 'kappa' => 10, 'lambda' => 11, 'mu' => 12, 'nu' => 13, 'xi' => 14];
// dresscode:enable

disable bez jména vypne všechna pravidla až po enable; bez enable až do konce souboru.

V souboru

<?php // dresscode:ignore-file

Komentář kdekoli v souboru vypne pro něj všechna pravidla. Hodí se pro generovaný kód, který leží mezi ručně psaným; když generovaných souborů je víc, je čistší je vyloučit cestou nebo podle obsahu (skipWhen v konfiguraci).

Pro cestu

Výjimka, která platí pro celý adresář, patří do konfigurace, ne do stovky souborů:

excludeRulePaths:
	dresscode/strict-comparison: [legacy]
	dresscode/line-length: [tests/fixtures]

Soubor pak zkontroluje zbytek pravidel. Celé cesty vynechá excludePaths; obojí je popsané v Konfiguraci.

Baseline

Na projektu s tisíci porušeními má první fix podobu jednoho obřího commitu. Někdy je to přesně to, co chcete udělat a mít za sebou. Někdy ne: kód se právě reviduje na jiné větvi, tým na to nemá týden, nebo chcete pravidlo zapnout jen pro nový kód. Pro ty případy je baseline.

vendor/bin/dresscode check --generate-baseline

Baseline with 1408 violations written to dresscode-baseline.neon.
Name it in the configuration to make it apply.

Soubor vznikne vedle konfigurace a má její formát (.neon vedle dresscode.neon, .php vedle dresscode.php). Platí od chvíle, kdy ho konfigurace pojmenuje:

baseline: dresscode-baseline.neon

Uvnitř je pro každý soubor seznam porušení s pravidlem, zprávou a otiskem:

files:
	src/Cart.php:
		-
			rule: dresscode/strict-comparison
			message: 'The == comparison must be written ''==='''
			fingerprint: a91a46b053d6d827

Otisk se počítá z pravidla, zprávy a obsahu řádku, ne z jeho čísla, takže baseline přežije úpravy jinde v souboru. Porušení z baseline se nehlásí ani neopravují a shrnutí běhu je přizná, aby nikdo nežil v omylu, že je čisto:

OK  1408 violations in the baseline in 214 files

Když porušení z baseline zmizí, protože ho někdo opravil, běh upozorní, že položka už ničemu neodpovídá, a stačí baseline vygenerovat znovu. Baseline se má zmenšovat; jakmile je prázdná, řádek z konfigurace smažte a soubor s ním.