Zašto je naša konfiguraciona datoteka uglavnom komentar
U ovom članku
Datoteka .htaccess na ovom serveru ima 478 linija. 98 njih su pravila. 309 su komentari.
Tri linije objašnjenja na svaku liniju koja nešto radi. Taj odnos nije planiran; tako ispadne kada je pravilo za pisanje pravila da razlog mora stajati pored njega.
Zašto pravilo za prepisivanje traži pasus
Pravilo u konfiguraciji servera neobično je neprijazno prema kasnijem čitanju. Namerno je zbijeno, nema ime, ne može se izvršavati korak po korak, a njegovo dejstvo je nevidljivo osim ako se baš ne zatraži prava adresa. Šest meseci kasnije, jedini pošten odgovor na „zašto je ovo ovde“ obično je nagađanje.
Gore od toga, pogrešno nagađanje je jeftino i deluje bezbedno. Pravilo koje niko ne razume je pravilo koje neko na kraju obriše pri sređivanju, i ono što je sprečavalo se vraća.
Zato svako pravilo ovde nosi čemu služi i gde se to može proveriti. Jedanaest linija komentara nosi datum, dvanaest izmerenu brojku. To su dve stvari koje budućem čitaocu omogućavaju da odluči da li razlog još važi.
Tri pravila koja ne bi preživela bez komentara
Jezički kôd koji je ličio na ekstenziju skripte. Pravilo koje blokira zaostale izvorne datoteke poklapalo je ekstenzije, a jedna od njih bila je .pl — Perl. Pregledi dizajna zovu se 2900.pl.svg, gde je pl poljski. Svaki poljski pregled počeo je da odgovara sa 403, dok su svi ostali jezici radili. Komentar sada kaže da pl namerno nedostaje na listi, zašto, i šta je izmereno kog dana. Bez toga bi ga sledeći ko sređuje listu vratio.
Dva prekidača tamo gde jedan izgleda dovoljno. Unapred komprimovane datoteke ne smeju se komprimovati ponovo pri slanju. Konfiguracija postavlja no-gzip, čime se zaustavlja jedan od dva kompresora servera. Drugi je ponovo komprimovao gotovu datoteku dok je zaglavlje i dalje najavljivalo gzip, pa su pregledači dobijali nečitljiv sadržaj. Komentar objašnjava zašto su tu i no-gzip i no-brotli zajedno, jer uklanjanje drugog izgleda kao sređivanje.
Pravilo zabrane koje je obrnuto. Pravilo koje blokira rezervne kopije ne navodi zabranjene ekstenzije. Ono pita da li naziv datoteke sadrži izvornu ekstenziju koja nije na kraju — što hvata nazive koje još niko nije smislio. Komentar navodi pet naziva koje je očigledna verzija pogrešno obradila, zajedno sa njihovim statusnim kodovima. Pročitajte samo pravilo i izgleda nepotrebno pametno; pročitajte komentar i izgleda kao jedina stvar koja funkcioniše.
Opšta verzija
Komentari koji prepričavaju kôd bezvredni su i svi to znaju. Ovi nisu takvi. Beleže ono što kôd ne može: šta je pošlo naopako, šta je izmereno, kog datuma, i koja je alternativa odbačena.
Test da li vredi napisati komentar dovoljno je jednostavan. Ako bi liniju iznad njega obrisao neko ko ne zna priču, da li bi se nešto tiho pokvarilo? Ako da, zapišite priču. Ako ne, ne pišite ništa.
Tri prema jedan nije cilj. To je ono što je taj test dao na datoteci u kojoj gotovo svaka linija postoji zato što je nešto konkretno pošlo naopako.