The config file that explains itself

The .htaccess on this server is 478 lines long. 98 of them are rules. 309 are comments.

Three lines of explanation for every line that does something. That ratio was not planned; it is what happens when the rule for writing a rule is that the reason has to go next to it.

Why a rewrite rule needs a paragraph

A rule in a server configuration is unusually hostile to being read later. It is terse by design, it has no name, it cannot be stepped through, and its effect is invisible unless you happen to request exactly the right address. Six months on, the only honest answer to "why is this here" is usually a guess.

Worse, guessing wrong is cheap and looks safe. A rule nobody understands is a rule somebody eventually deletes during a tidy-up, and the thing it was preventing comes back.

So each rule here carries what it is for, and where it can be checked. Eleven of the comment lines carry a date, twelve carry a measured figure. Those are the two things that let a future reader decide whether the reason still holds.

Three that would not survive without their comment

A language code that looked like a script extension. A rule blocking leftover source files matched on extension, and one of the extensions was .pl — Perl. Design previews are named 2900.pl.svg, where pl is Polish. Every Polish preview started answering 403 while every other language was fine. The comment now says that pl is deliberately absent from the list, why, and what was measured on which day. Without that, the next person tidying the list puts it back.

Two switches where one looks sufficient. Pre-compressed files must not be compressed again on the way out. The configuration sets no-gzip, which stops one of the server's two compressors. The other one re-compressed the finished file while the header still announced gzip, and browsers got unreadable content. The comment explains why both no-gzip and no-brotli are there, because removing the second looks like tidying.

A deny rule that is inverted. The rule that blocks backup copies does not list forbidden extensions. It asks whether a filename contains a source extension that is not at the end — which catches the names nobody has invented yet. The comment lists the five names that the obvious version got wrong, with their status codes. Read the rule alone and it looks needlessly clever; read the comment and it looks like the only thing that works.

The general version

Comments that restate the code are worthless and everybody knows it. That is not what these are. They record the thing the code cannot: what went wrong, what was measured, on what date, and what the alternative was that got rejected.

The test for whether a comment is worth writing is simple enough. If the line above it were deleted by somebody who did not know the story, would something break silently? If yes, write the story down. If no, do not write anything.

Three to one is not a target. It is what that test produced on a file where nearly every line exists because something specific went wrong.