Varför vår konfigurationsfil mest består av kommentarer
Filen .htaccess på den här servern är 478 rader lång. 98 av dem är regler. 309 är kommentarer.
Tre rader förklaring för varje rad som gör något. Den kvoten var inte planerad; det är vad som händer när regeln för att skriva en regel är att skälet ska stå bredvid den.
Varför en omskrivningsregel behöver ett helt stycke
En regel i en serverkonfiguration är ovanligt svår att läsa i efterhand. Den är kortfattad av princip, den har inget namn, den går inte att stega igenom, och dess effekt syns inte om inte exakt rätt adress råkar efterfrågas. Ett halvår senare är det enda ärliga svaret på ”varför står det här” oftast en gissning.
Värre är att en felaktig gissning är billig och ser säker ut. En regel som ingen förstår är en regel som någon till slut raderar vid en städning, och det den förhindrade kommer tillbaka.
Därför har varje regel här med sig vad den är till för och var det går att kontrollera. Elva av kommentarsraderna har ett datum, tolv har ett uppmätt värde. Det är de två saker som låter en framtida läsare avgöra om skälet fortfarande gäller.
Tre som inte skulle överleva utan sin kommentar
En språkkod som såg ut som en skriptändelse. En regel som blockerar kvarglömda källkodsfiler matchade på filändelse, och en av ändelserna var .pl — Perl. Förhandsvisningar av designer heter 2900.pl.svg, där pl är polska. Varje polsk förhandsvisning började svara 403, medan alla andra språk fungerade. Kommentaren säger nu att pl medvetet saknas i listan, varför, och vad som mättes vilken dag. Utan den lägger nästa person som städar listan tillbaka den.
Två brytare där en ser ut att räcka. Förkomprimerade filer får inte komprimeras igen på vägen ut. Konfigurationen sätter no-gzip, vilket stoppar en av serverns två komprimerare. Den andra komprimerade om den färdiga filen medan headern fortfarande angav gzip, och webbläsarna fick oläsligt innehåll. Kommentaren förklarar varför både no-gzip och no-brotli finns där, eftersom det ser ut som städning att ta bort den andra.
En spärregel som är inverterad. Regeln som blockerar säkerhetskopior listar inte förbjudna ändelser. Den frågar om ett filnamn innehåller en källkodsändelse som inte står i slutet — vilket fångar de namn som ingen har hittat på än. Kommentaren listar de fem namn som den uppenbara versionen hanterade fel, med sina statuskoder. Läser man regeln ensam ser den onödigt listig ut; läser man kommentaren ser den ut som det enda som fungerar.
Den allmänna versionen
Kommentarer som upprepar koden är värdelösa, och det vet alla. Det är inte vad de här är. De dokumenterar det som koden inte kan: vad som gick fel, vad som mättes, vilket datum, och vilket alternativ som förkastades.
Testet för om en kommentar är värd att skriva är enkelt nog. Om raden ovanför den raderades av någon som inte kände till historien, skulle något då gå sönder i tysthet? Om ja, skriv ner historien. Om nej, skriv ingenting.
Tre till en är inget mål. Det är vad det testet gav i en fil där nästan varje rad finns för att något specifikt gick fel.