Plik konfiguracyjny, który sam się tłumaczy

.htaccess na tym serwerze ma 478 wierszy. 98 z nich to reguły. 309 to komentarze.

Trzy wiersze wyjaśnienia na każdy wiersz, który coś robi. Ta proporcja nie była planowana; tak wychodzi, gdy zasadą pisania reguły jest to, że powód musi stanąć obok.

Dlaczego reguła przepisywania potrzebuje akapitu

Reguła w konfiguracji serwera jest wyjątkowo wroga późniejszemu czytaniu. Jest z założenia zwięzła, nie ma nazwy, nie da się przez nią przejść krokiem, a jej działanie jest niewidoczne, dopóki nie poprosi się akurat o właściwy adres. Pół roku później jedyną uczciwą odpowiedzią na „dlaczego to tu jest" jest zwykle zgadywanie.

Gorzej: pomylić się w zgadywaniu jest tanio i wygląda bezpiecznie. Reguła, której nikt nie rozumie, to reguła, którą ktoś kiedyś skasuje przy porządkach, a to, czemu zapobiegała, wraca.

Dlatego każda reguła niesie tu, po co jest i gdzie można to sprawdzić. Jedenaście wierszy komentarza niesie datę, dwanaście niesie zmierzoną wartość. To dwie rzeczy, które pozwalają przyszłemu czytelnikowi ocenić, czy powód nadal obowiązuje.

Trzy, które nie przetrwałyby bez swojego komentarza

Kod języka, który wyglądał jak rozszerzenie skryptu. Reguła blokująca zapomniane pliki źródłowe dopasowywała rozszerzenia, a jednym z nich było .pl — Perl. Podglądy wzorów nazywają się 2900.pl.svg, gdzie pl to polski. Każdy polski podgląd zaczął odpowiadać 403, a wszystkie inne języki były w porządku. Komentarz mówi teraz, że pl celowo nie ma na liście, dlaczego, i co zmierzono którego dnia. Bez tego następna osoba porządkująca listę wstawia je z powrotem.

Dwa przełączniki tam, gdzie jeden wydaje się wystarczać. Pliki wstępnie skompresowane nie mogą zostać skompresowane po raz drugi w drodze na zewnątrz. Konfiguracja ustawia no-gzip, co zatrzymuje jeden z dwóch kompresorów serwera. Drugi pakował gotowy plik jeszcze raz, podczas gdy nagłówek dalej ogłaszał gzip, a przeglądarki dostawały treść nie do odczytania. Komentarz wyjaśnia, dlaczego stoją oba, no-gzip i no-brotli, bo usunięcie drugiego wygląda na porządki.

Reguła zakazu, która jest odwrócona. Reguła blokująca kopie zapasowe nie wylicza zakazanych rozszerzeń. Pyta, czy nazwa pliku zawiera rozszerzenie źródłowe, które nie stoi na końcu — i tym łapie nazwy, których nikt jeszcze nie wymyślił. Komentarz wylicza pięć nazw, na których oczywista wersja się pomyliła, wraz z ich kodami stanu. Przeczytaj samą regułę, a wygląda niepotrzebnie sprytnie; przeczytaj komentarz, a wygląda na jedyne, co działa.

Wersja ogólna

Komentarze powtarzające kod są bezwartościowe i każdy o tym wie. Te takie nie są. Zapisują to, czego kod nie umie: co poszło nie tak, co zmierzono, którego dnia i jaka alternatywa została odrzucona.

Próba na to, czy komentarz wart jest napisania, jest dość prosta. Gdyby wiersz nad nim skasował ktoś, kto nie zna tej historii, czy coś zepsułoby się po cichu? Jeśli tak, spisz historię. Jeśli nie, nie pisz nic.

Trzy do jednego nie jest celem. To wynik tej próby w pliku, w którym prawie każdy wiersz istnieje dlatego, że coś konkretnego poszło nie tak.