Файл настроек, который объясняет сам себя

.htaccess на этом сервере длиной 478 строк. 98 из них — правила. 309 — комментарии.

Три строки объяснения на каждую строку, которая что-то делает. Это соотношение не планировали; оно выходит само, когда правило написания правила гласит, что причина должна стоять рядом.

Почему правилу переписывания нужен абзац

Правило в настройках сервера необычайно враждебно к позднему чтению. Оно намеренно кратко, у него нет имени, по нему нельзя пройти шагами, а его действие невидимо, пока не запросишь ровно нужный адрес. Полгода спустя единственный честный ответ на «почему это здесь» обычно догадка.

Хуже того: догадаться неверно дёшево и выглядит безопасно. Правило, которого никто не понимает, — это правило, которое кто-нибудь однажды удалит при уборке, и то, что оно предотвращало, вернётся.

Поэтому каждое правило здесь несёт, для чего оно, и где это можно проверить. Одиннадцать строк комментария несут дату, двенадцать — измеренное значение. Это те две вещи, по которым будущий читатель может решить, действует ли причина до сих пор.

Три, которые не выжили бы без своего комментария

Код языка, который выглядел как расширение скрипта. Правило против забытых исходных файлов срабатывало по расширению, и одним из них было .pl — Perl. Предпросмотры оформлений называются 2900.pl.svg, где pl — польский. Каждый польский предпросмотр начал отвечать 403, тогда как все остальные языки были в порядке. Комментарий теперь говорит, что pl намеренно нет в списке, почему, и что было измерено в какой день. Без этого следующий, кто наведёт в списке порядок, вернёт его обратно.

Два переключателя там, где хватает одного. Предварительно сжатые файлы нельзя сжимать ещё раз на выходе. Настройка ставит no-gzip, что останавливает один из двух сжимателей сервера. Второй пережимал готовый файл, пока заголовок по-прежнему объявлял gzip, и браузеры получали нечитаемое содержимое. Комментарий объясняет, зачем стоят оба, no-gzip и no-brotli, потому что убрать второй выглядит уборкой.

Запрет, который вывернут наизнанку. Правило против резервных копий не перечисляет запрещённые расширения. Оно спрашивает, содержит ли имя файла исходное расширение, которое не стоит в конце — и так ловит имена, которых ещё никто не придумал. Комментарий перечисляет пять имён, на которых очевидная версия ошиблась, с их кодами ответа. Прочитаешь одно правило — выглядит без нужды хитро; прочитаешь комментарий — выглядит единственным, что работает.

Общая формулировка

Комментарии, повторяющие код, ничего не стоят, и это знают все. Эти не такие. Они записывают то, чего код не может: что пошло не так, что было измерено, в какой день, и какая альтернатива была отвергнута.

Проверка на то, стоит ли писать комментарий, достаточно проста. Если строку над ним удалит тот, кто не знает истории, сломается ли что-нибудь молча? Если да — запиши историю. Если нет — не пиши ничего.

Три к одному — не цель. Это то, что дала эта проверка в файле, где почти каждая строка существует потому, что что-то определённое пошло не так.