Potlačení pravidel 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 do kódu je nepíšu; když už, tak v konfiguraci pro celou cestu. Jsou ale místa, kde pravidlo prostě nemá pravdu, a tam se hodí přesný nástroj a ne kladivo. Potlačení (anglicky suppression) má čtyři úrovně, od nejužší po nejširší:

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

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

Potlačení 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 se odděluje čá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 několik řá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á. Stejně tak rozumí komentářům phpcs:ignore, phpcs:disable, phpcs:enable, phpcs:ignoreFile a anotaci @phpcsSuppress, takže kdo přechází z jiného nástroje, nemusí do kódu vůbec sáhnout. Přepis na nová jména pak udělá dresscode migrate-suppressions.

Potlačení 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 platí do konce souboru.

Potlačení v celém souboru

<?php // dresscode:ignore-file

Tenhle komentář kdekoli v souboru vypne pro celý soubor všechna pravidla. Hodí se pro generovaný kód, který leží mezi ručně psaným. Když je takových souborů víc, je čistší vyloučit je cestou nebo podle obsahu, viz skipWhen v konfiguraci.

Vypnutí 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]

Zbytek pravidel takový soubor zkontroluje normálně. Celé cesty vynechá excludePaths; obojí popisuje stránka Konfigurace.

Baseline

Na projektu s tisíci porušeními by první fix znamenal jeden obří commit. 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 nové pravidlo zapnout jen pro nově psaný kód. Pro tyhle případy je baseline, tedy soupis porušení, která se dnes nemají hlásit.

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 ve stejném formátu (.neon vedle dresscode.neon, .php vedle dresscode.php). Platit začne ve chvíli, 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í, která jsou v baseline, se nehlásí ani neopravují, a shrnutí běhu je přizná, aby nikdo nežil v domnění, že je uklizeno:

OK  1408 violations in the baseline in 214 files

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