Proč jsou v našem konfiguračním souboru hlavně komentáře

Soubor .htaccess na tomto serveru má 478 řádků. Pravidel je z nich 98. Komentářů 309.

Tři řádky vysvětlení na každý řádek, který něco dělá. Ten poměr nebyl plánovaný; vznikne sám, když pravidlo pro psaní pravidel zní, že důvod musí stát hned vedle.

Proč přepisovací pravidlo potřebuje odstavec

Pravidlo v konfiguraci serveru se pozdějšímu čtení neobvykle vzpírá. Je záměrně strohé, nemá jméno, nedá se krokovat a jeho účinek je neviditelný, pokud se nepožádá přesně o tu správnou adresu. Po šesti měsících je jedinou poctivou odpovědí na otázku „proč tu tohle je“ obvykle odhad.

Horší je, že špatný odhad je levný a vypadá bezpečně. Pravidlo, kterému nikdo nerozumí, je pravidlo, které někdo při úklidu nakonec smaže, a to, čemu bránilo, se vrátí.

Každé pravidlo tu proto nese, k čemu slouží a kde se to dá ověřit. Jedenáct řádků komentářů nese datum, dvanáct naměřenou hodnotu. To jsou dvě věci, které budoucímu čtenáři dovolí rozhodnout, zda důvod stále platí.

Tři, které by bez komentáře nepřežily

Kód jazyka, který vypadal jako přípona skriptu. Pravidlo blokující zbylé zdrojové soubory porovnávalo přípony a jednou z nich byla .pl — Perl. Náhledy designů se jmenují 2900.pl.svg, kde pl je polština. Každý polský náhled začal odpovídat 403, zatímco všechny ostatní jazyky byly v pořádku. Komentář teď říká, že pl v seznamu úmyslně chybí, proč, a co se kterého dne naměřilo. Bez toho by ji další člověk, který seznam uklízí, vrátil zpět.

Dva přepínače tam, kde se zdá, že stačí jeden. Předkomprimované soubory se na cestě ven nesmějí komprimovat znovu. Konfigurace nastavuje no-gzip, což zastaví jeden ze dvou kompresorů serveru. Ten druhý hotový soubor znovu zkomprimoval, zatímco hlavička stále hlásila gzip, a prohlížeče dostaly nečitelný obsah. Komentář vysvětluje, proč jsou tam no-gzip i no-brotli zároveň, protože odstranění druhého vypadá jako úklid.

Zakazující pravidlo, které je obrácené. Pravidlo, které blokuje záložní kopie, nevyjmenovává zakázané přípony. Ptá se, zda název souboru obsahuje zdrojovou příponu, která není na konci — a tím zachytí i názvy, které si ještě nikdo nevymyslel. Komentář uvádí pět názvů, na kterých zjevná verze selhala, i s jejich stavovými kódy. Čtete-li samotné pravidlo, působí zbytečně vychytrale; čtete-li komentář, působí jako jediná věc, která funguje.

Obecná verze

Komentáře, které opakují kód, jsou bezcenné, a to ví každý. Tyhle takové nejsou. Zaznamenávají to, co kód nedokáže: co se pokazilo, co se naměřilo, kterého dne a jaká alternativa byla zamítnuta.

Test, zda komentář stojí za napsání, je dost jednoduchý. Kdyby řádek nad ním smazal někdo, kdo nezná příběh, rozbilo by se něco potichu? Pokud ano, příběh zapište. Pokud ne, nepište nic.

Tři ku jedné není cíl. Je to výsledek toho testu na souboru, kde téměř každý řádek existuje proto, že se pokazilo něco konkrétního.