会自我解释的配置文件

这台服务器上的 .htaccess 有 478 行。其中 98 行是规则。309 行是注释。

每一行做事的代码配三行解释。这个比例不是计划出来的；当写规则的规则是理由必须挨着它时，自然就会这样。

为什么一条重写规则需要一个段落

服务器配置里的一条规则对日后的阅读格外不友好。它天生简短，没有名字，没法单步走过，而且除非你正好请求了那个地址，否则它的作用是看不见的。半年之后，对「这行为什么在这里」唯一诚实的回答通常是猜测。

更糟的是，猜错很便宜，看上去还很安全。没人懂的规则，就是某天在整理中被人删掉的规则，而它挡住的东西会回来。

所以这里每条规则都带着它是干什么的，以及在哪儿可以核对。十一行注释带着日期，十二行带着实测数值。这两样东西让后来的读者能判断，那个理由是否依然成立。

三条没有注释就活不下来的规则

一个看起来像脚本扩展名的语言代码。 一条拦截残留源文件的规则按扩展名匹配，其中一个是 .pl — Perl。样式预览图的名字是 2900.pl.svg，这里的 pl 指波兰语。每一张波兰语预览图都开始返回 403，而其他所有语言都正常。注释现在写明 pl 是故意不在列表里的，为什么，以及哪一天测了什么。没有这些，下一个整理列表的人会把它加回去。

一个开关看起来就够，却放了两个。 预压缩过的文件在送出去时不能再被压缩一次。配置里设了 no-gzip，它拦住了服务器两个压缩器中的一个。另一个把已经压好的文件又压了一遍，而响应头仍然声称是 gzip，浏览器拿到的是读不出来的内容。注释解释了为什么 no-gzip 和 no-brotli 两个都在，因为去掉第二个看起来就像在做整理。

一条反过来写的拒绝规则。 拦截备份副本的那条规则并不列举被禁止的扩展名。它问的是文件名里是否含有一个不在末尾的源码扩展名 — 这样就抓住了还没人发明出来的名字。注释列出了显而易见的那个版本弄错的五个名字，连同它们的状态码。单读规则，它显得多此一举地聪明；读了注释，它显得是唯一管用的东西。

一般化的说法

复述代码的注释毫无价值，这一点人人都知道。这些不是那种。它们记下代码记不下的东西：出了什么错，测了什么，哪一天测的，以及被否掉的替代方案是什么。

判断一条注释值不值得写的检验足够简单。如果它上面那一行被一个不知道这段来历的人删掉，会不会有东西无声地坏掉？如果会，就把来历写下来。如果不会，就什么都别写。

三比一不是目标。它是这套检验在一个几乎每行都因为某件具体的事出过错而存在的文件里得出的结果。