Waarom ons configuratiebestand grotendeels commentaar is

De .htaccess op deze server is 478 regels lang. 98 daarvan zijn regels die iets doen. 309 zijn commentaar.

Drie regels uitleg voor elke regel die iets doet. Die verhouding was niet gepland; het is wat er gebeurt wanneer de regel voor het schrijven van een regel is dat de reden ernaast moet komen.

Waarom een herschrijfregel een alinea nodig heeft

Een regel in een serverconfiguratie is ongewoon vijandig om later te lezen. Hij is met opzet kort, hij heeft geen naam, je kunt er niet doorheen stappen, en zijn effect is onzichtbaar tenzij precies het juiste adres toevallig wordt opgevraagd. Zes maanden later is het enige eerlijke antwoord op "waarom staat dit hier" meestal een gok.

Erger nog, verkeerd gokken is goedkoop en ziet er veilig uit. Een regel die niemand begrijpt, is een regel die iemand uiteindelijk bij een opruimbeurt verwijdert, en dan komt terug wat hij tegenhield.

Elke regel hier draagt dus wat hij moet doen, en waar het na te kijken is. Elf van de commentaarregels dragen een datum, twaalf dragen een gemeten cijfer. Dat zijn de twee dingen waarmee een latere lezer kan beslissen of de reden nog geldt.

Drie die het zonder hun commentaar niet zouden overleven

Een taalcode die op een scriptextensie leek. Een regel die achtergebleven bronbestanden blokkeerde, keek naar de extensie, en een van de extensies was .pl — Perl. Ontwerpvoorbeelden heten 2900.pl.svg, waarbij pl Pools is. Elk Pools voorbeeld begon met 403 te antwoorden terwijl elke andere taal in orde was. Het commentaar zegt nu dat pl met opzet niet op de lijst staat, waarom, en wat er op welke dag gemeten is. Zonder dat zet de volgende die de lijst opruimt hem er weer bij.

Twee schakelaars waar er één genoeg lijkt. Vooraf gecomprimeerde bestanden mogen onderweg naar buiten niet nogmaals gecomprimeerd worden. De configuratie zet no-gzip, wat een van de twee compressoren van de server stopt. De andere comprimeerde het afgewerkte bestand opnieuw terwijl de kop nog gzip aankondigde, en browsers kregen onleesbare inhoud. Het commentaar legt uit waarom zowel no-gzip als no-brotli er staan, want de tweede weghalen ziet eruit als opruimen.

Een verbodsregel die omgekeerd is. De regel die reservekopieën blokkeert, somt geen verboden extensies op. Hij vraagt of een bestandsnaam een bronextensie bevat die niet aan het eind staat — en dat vangt de namen die nog niemand bedacht heeft. Het commentaar somt de vijf namen op die de voor de hand liggende versie fout deed, met hun statuscodes. Lees de regel alleen en hij lijkt nodeloos slim; lees het commentaar en hij lijkt het enige dat werkt.

De algemene versie

Commentaar dat de code herhaalt is waardeloos en iedereen weet het. Dat is niet wat dit is. Het legt vast wat de code niet kan: wat er misging, wat er gemeten is, op welke datum, en welk alternatief is afgewezen.

De toets of een opmerking het schrijven waard is, is eenvoudig genoeg. Zou de regel erboven verwijderd worden door iemand die het verhaal niet kent, zou er dan geruisloos iets kapotgaan? Zo ja, schrijf het verhaal op. Zo nee, schrijf niets.

Drie op één is geen streefgetal. Het is wat die toets opleverde in een bestand waarin bijna elke regel bestaat omdat er iets bepaalds misging.