Die Konfigurationsdatei, die sich selbst erklärt
Die .htaccess auf diesem Server ist 478 Zeilen lang. 98 davon sind Regeln. 309 sind Kommentar.
Drei Zeilen Erklärung auf jede Zeile, die etwas tut. Dieses Verhältnis war nicht geplant; es entsteht, wenn die Regel fürs Regelschreiben lautet, dass der Grund danebenstehen muss.
Warum eine Umschreiberegel einen Absatz braucht
Eine Regel in einer Serverkonfiguration ist ungewöhnlich feindlich gegen späteres Lesen. Sie ist absichtlich knapp, sie hat keinen Namen, man kann nicht durch sie hindurchsteppen, und ihre Wirkung ist unsichtbar, solange man nicht zufällig genau die richtige Adresse aufruft. Ein halbes Jahr später ist die einzige ehrliche Antwort auf „warum steht das hier" meistens eine Vermutung.
Schlimmer noch: falsch zu raten ist billig und sieht sicher aus. Eine Regel, die niemand versteht, ist eine Regel, die irgendwann beim Aufräumen jemand löscht, und das, was sie verhindert hat, kommt zurück.
Jede Regel hier trägt deshalb, wofür sie da ist und wo man es nachprüfen kann. Elf der Kommentarzeilen tragen ein Datum, zwölf einen gemessenen Wert. Das sind die zwei Dinge, mit denen ein späterer Leser entscheiden kann, ob der Grund noch gilt.
Drei, die ohne ihren Kommentar nicht überleben würden
Ein Sprachkürzel, das wie eine Skriptendung aussah. Eine Regel gegen liegengebliebene Quelldateien griff auf Endungen, und eine davon war .pl — Perl. Entwurfsvorschauen heißen 2900.pl.svg, wobei pl für Polnisch steht. Jede polnische Vorschau antwortete mit 403, während jede andere Sprache in Ordnung war. Der Kommentar sagt jetzt, dass pl absichtlich nicht in der Liste steht, warum, und was an welchem Tag gemessen wurde. Ohne das setzt der Nächste, der die Liste aufräumt, es wieder hinein.
Zwei Schalter, wo einer zu genügen scheint. Vorkomprimierte Dateien dürfen auf dem Weg nach draußen nicht noch einmal komprimiert werden. Die Konfiguration setzt no-gzip, was einen der beiden Komprimierer des Servers aufhält. Der andere packte die fertige Datei erneut, während der Kopf weiter gzip behauptete, und Browser bekamen unlesbaren Inhalt. Der Kommentar erklärt, warum beide dastehen, no-gzip und no-brotli, denn den zweiten zu entfernen sieht nach Aufräumen aus.
Eine Sperre, die umgedreht ist. Die Regel gegen Sicherungskopien zählt keine verbotenen Endungen auf. Sie fragt, ob ein Dateiname eine Quellendung enthält, die nicht am Ende steht — und fängt damit die Namen, die noch niemand erfunden hat. Der Kommentar führt die fünf Namen auf, bei denen die naheliegende Fassung danebenlag, samt ihren Statuscodes. Liest man nur die Regel, wirkt sie unnötig clever; liest man den Kommentar, wirkt sie wie das Einzige, was funktioniert.
Die allgemeine Fassung
Kommentare, die den Code wiederholen, sind wertlos, und das weiß jeder. Das sind diese nicht. Sie halten fest, was der Code nicht kann: was schiefging, was gemessen wurde, an welchem Tag, und welche Alternative verworfen wurde.
Die Probe, ob ein Kommentar das Schreiben wert ist, ist einfach genug. Wenn jemand die Zeile darüber löschte, der die Geschichte nicht kennt — ginge dann lautlos etwas kaputt? Wenn ja, schreib die Geschichte auf. Wenn nein, schreib nichts.
Drei zu eins ist kein Ziel. Es ist, was diese Probe in einer Datei ergeben hat, in der fast jede Zeile existiert, weil etwas Bestimmtes schiefgegangen ist.