Защо конфигурационният ни файл е предимно коментари

Файлът .htaccess на този сървър е дълъг 478 реда. 98 от тях са правила. 309 са коментари.

Три реда обяснение за всеки ред, който върши нещо. Това съотношение не беше планирано; така става, когато правилото за писане на правило гласи, че причината трябва да стои до него.

Защо едно правило за пренаписване има нужда от абзац

Едно правило в конфигурацията на сървър необичайно трудно се чете по-късно. То е лаконично по замисъл, няма име, не може да се изпълни стъпка по стъпка и действието му е невидимо, освен ако не бъде поискан точно правилният адрес. Шест месеца по-късно единственият честен отговор на „защо е тук това“ обикновено е предположение.

По-лошото е, че грешното предположение е евтино и изглежда безопасно. Правило, което никой не разбира, е правило, което някой рано или късно изтрива при подреждане, и онова, което то е предотвратявало, се връща.

Затова всяко правило тук носи информация за какво служи и къде може да се провери. Единадесет от редовете с коментари съдържат дата, дванадесет съдържат измерена стойност. Това са двете неща, които позволяват на бъдещия читател да реши дали причината все още е в сила.

Три правила, които не биха оцелели без коментара си

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

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

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

Общият случай

Коментарите, които преразказват кода, са безполезни и всички го знаят. Тези не са такива. Те записват онова, което кодът не може: какво се е объркало, какво е измерено, на коя дата и каква е била алтернативата, която е отхвърлена.

Тестът дали един коментар си струва да бъде написан е достатъчно прост. Ако редът над него бъде изтрит от някой, който не знае историята, ще се счупи ли нещо безшумно? Ако да, запишете историята. Ако не, не пишете нищо.

Три към едно не е цел. Това е резултатът от този тест във файл, в който почти всеки ред съществува, защото нещо конкретно се е объркало.