O ficheiro de configuração que se explica sozinho

O .htaccess deste servidor tem 478 linhas. 98 delas são regras. 309 são comentários.

Três linhas de explicação para cada linha que faz alguma coisa. Essa proporção não foi planeada; é o que sai quando a regra para escrever uma regra é que o motivo tem de ficar ao lado.

Porque é que uma regra de reescrita precisa de um parágrafo

Uma regra numa configuração de servidor é invulgarmente hostil a ser lida mais tarde. É lacónica por desenho, não tem nome, não se pode percorrer passo a passo, e o seu efeito é invisível a não ser que se peça precisamente o endereço certo. Seis meses depois, a única resposta honesta a „porque é que isto está aqui" é normalmente um palpite.

Pior: errar o palpite é barato e parece seguro. Uma regra que ninguém entende é uma regra que alguém acaba por apagar numa arrumação, e aquilo que ela impedia volta.

Por isso cada regra leva aqui para que serve e onde se pode verificar. Onze das linhas de comentário levam uma data, doze levam um valor medido. São as duas coisas que permitem a um leitor futuro decidir se o motivo ainda se mantém.

Três que não sobreviveriam sem o seu comentário

Um código de língua que parecia uma extensão de script. Uma regra que bloqueava ficheiros de código esquecidos actuava por extensão, e uma delas era .pl — Perl. As pré-visualizações dos modelos chamam-se 2900.pl.svg, onde pl é polaco. Todas as pré-visualizações polacas começaram a responder 403 enquanto todas as outras línguas estavam bem. O comentário diz agora que pl está deliberadamente fora da lista, porquê, e o que foi medido em que dia. Sem isso, a próxima pessoa a arrumar a lista volta a pô-lo lá.

Dois interruptores onde um parece bastar. Os ficheiros pré-comprimidos não podem ser comprimidos outra vez à saída. A configuração põe no-gzip, o que trava um dos dois compressores do servidor. O outro voltava a comprimir o ficheiro pronto enquanto o cabeçalho ainda anunciava gzip, e os navegadores recebiam conteúdo ilegível. O comentário explica porque estão lá ambos, no-gzip e no-brotli, porque tirar o segundo parece arrumação.

Uma regra de negação que está invertida. A regra que bloqueia cópias de segurança não enumera extensões proibidas. Pergunta se um nome de ficheiro contém uma extensão de código que não está no fim — e assim apanha os nomes que ainda ninguém inventou. O comentário enumera os cinco nomes em que a versão óbvia falhou, com os seus códigos de estado. Lê-se a regra sozinha e parece desnecessariamente esperta; lê-se o comentário e parece a única coisa que funciona.

A versão geral

Comentários que repetem o código não valem nada e toda a gente sabe. Estes não são isso. Registam aquilo que o código não consegue: o que correu mal, o que foi medido, em que dia, e qual foi a alternativa rejeitada.

O teste para saber se vale a pena escrever um comentário é bastante simples. Se a linha acima fosse apagada por alguém que não conhece a história, partia-se alguma coisa em silêncio? Se sim, escreve a história. Se não, não escrevas nada.

Três para um não é um objectivo. É o que esse teste produziu num ficheiro onde quase todas as linhas existem porque alguma coisa concreta correu mal.