Prečo náš konfiguračný súbor tvoria prevažne komentáre

Súbor .htaccess na tomto serveri má 478 riadkov. Z nich 98 sú pravidlá. Komentárov je 309.

Tri riadky vysvetlenia na každý riadok, ktorý niečo robí. Tento pomer nebol plánovaný; vznikne vtedy, keď pravidlo pre písanie pravidla vyžaduje uviesť dôvod hneď vedľa.

Prečo pravidlo prepisu potrebuje odsek

Pravidlo v konfigurácii servera je neobyčajne nepriateľské k neskoršiemu čítaniu. Je zámerne stručné, nemá názov, nemožno ním prechádzať po krokoch a jeho účinok je neviditeľný, pokiaľ sa náhodou nevyžiada presne správna adresa. O šesť mesiacov je jedinou poctivou odpoveďou na „prečo je to tu“ zvyčajne odhad.

Horšie je, že nesprávny odhad je lacný a vyzerá bezpečne. Pravidlo, ktorému nikto nerozumie, niekto napokon pri upratovaní odstráni a vec, ktorej bránilo, sa vráti.

Každé tunajšie pravidlo preto nesie vysvetlenie, na čo slúži a kde sa dá overiť. Jedenásť riadkov komentárov obsahuje dátum, dvanásť nameraný údaj. To sú dve veci, ktoré budúcemu čitateľovi umožnia rozhodnúť, či dôvod stále platí.

Tri, ktoré by bez komentára neprežili

Kód jazyka, ktorý vyzeral ako prípona skriptu. Pravidlo blokujúce zvyšné zdrojové súbory porovnávalo príponu a jednou z prípon bolo .pl — Perl. Náhľady dizajnov sa volajú 2900.pl.svg, kde pl je poľština. Každý poľský náhľad začal odpovedať 403, zatiaľ čo každý iný jazyk bol v poriadku. Komentár teraz hovorí, že pl v zozname zámerne chýba, prečo a čo sa meralo v ktorý deň. Bez toho ho ďalší človek pri upratovaní zoznamu vráti.

Dva prepínače tam, kde jeden vyzerá dostatočne. Vopred komprimované súbory sa pri odosielaní nesmú komprimovať znova. Konfigurácia nastavuje no-gzip, čo zastaví jeden z dvoch kompresorov servera. Druhý znovu komprimoval hotový súbor, kým hlavička stále oznamovala gzip, a prehliadače dostali nečitateľný obsah. Komentár vysvetľuje, prečo sú no-gzip aj no-brotli prítomné, pretože odstránenie druhého vyzerá ako upratovanie.

Obrátené pravidlo odmietania. Pravidlo blokujúce záložné kópie nevymenúva zakázané prípony. Pýta sa, či názov súboru obsahuje zdrojovú príponu, ktorá nie je na konci — čo zachytáva názvy, ktoré ešte nikto nevymyslel. Komentár uvádza päť názvov, pri ktorých zjavná verzia zlyhala, s ich stavovými kódmi. Prečítajte iba pravidlo a vyzerá zbytočne prefíkane; prečítajte komentár a vyzerá ako jediná vec, ktorá funguje.

Všeobecná verzia

Komentáre, ktoré opakujú kód, sú bezcenné a každý to vie. Tieto také nie sú. Zaznamenávajú to, čo kód nedokáže: čo zlyhalo, čo sa meralo, v aký deň a ktorá alternatíva bola zamietnutá.

Test toho, či sa oplatí komentár napísať, je dosť jednoduchý. Keby riadok nad ním odstránil niekto, kto nepozná príbeh, pokazilo by sa niečo potichu? Ak áno, zapíšte príbeh. Ak nie, nepíšte nič.

Tri ku jednej nie je cieľ. Je to výsledok tohto testu na súbore, kde takmer každý riadok existuje preto, že sa niečo konkrétne pokazilo.