Файл налаштувань, який пояснює сам себе

.htaccess на цьому сервері має 478 рядків. 98 з них — правила. 309 — коментарі.

Три рядки пояснення на кожен рядок, який щось робить. Це співвідношення не планували; воно виходить саме, коли правило написання правила каже, що причина має стояти поруч.

Чому правилу переписування потрібен абзац

Правило в налаштуваннях сервера напрочуд вороже до пізнішого читання. Воно навмисно стисле, не має імені, ним не можна пройти кроками, а його дія невидима, доки не запитаєш рівно потрібну адресу. Пів року по тому єдина чесна відповідь на «чому це тут» зазвичай здогад.

Гірше: здогадатися хибно дешево і виглядає безпечно. Правило, якого ніхто не розуміє, — це правило, яке хтось колись видалить під час прибирання, і те, чому воно запобігало, повернеться.

Тому кожне правило тут несе, для чого воно, і де це можна перевірити. Одинадцять рядків коментаря несуть дату, дванадцять — виміряне значення. Це ті дві речі, за якими майбутній читач може вирішити, чи причина досі чинна.

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

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

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

Заборона, яку вивернуто навиворіт. Правило проти резервних копій не перелічує заборонених розширень. Воно питає, чи містить ім'я файлу вихідне розширення, яке не стоїть у кінці — і так ловить імена, яких ще ніхто не вигадав. Коментар перелічує п'ять імен, на яких очевидна версія схибила, з їхніми кодами відповіді. Прочитаєш саме правило — виглядає без потреби хитро; прочитаєш коментар — виглядає єдиним, що працює.

Загальне формулювання

Коментарі, що повторюють код, нічого не варті, і це знають усі. Ці не такі. Вони записують те, чого код не може: що пішло не так, що було виміряно, якого дня, і яку альтернативу відкинули.

Перевірка на те, чи варто писати коментар, досить проста. Якщо рядок над ним видалить той, хто не знає історії, чи зламається щось мовчки? Якщо так — запиши історію. Якщо ні — не пиши нічого.

Три до одного — не мета. Це те, що дала ця перевірка у файлі, де майже кожен рядок існує тому, що щось конкретне пішло не так.