De ce fișierul nostru de configurare e format mai ales din comentarii
Fișierul .htaccess de pe acest server are 478 de linii. 98 dintre ele sunt reguli. 309 sunt comentarii.
Trei linii de explicație pentru fiecare linie care face ceva. Raportul nu a fost planificat; este ce se întâmplă atunci când regula pentru scrierea unei reguli este ca motivul să stea lângă ea.
De ce o regulă de rescriere are nevoie de un paragraf
O regulă dintr-o configurație de server este neobișnuit de ostilă lecturii ulterioare. Este concisă prin construcție, nu are nume, nu poate fi parcursă pas cu pas, iar efectul ei rămâne invizibil dacă nu se întâmplă să fie cerută exact adresa potrivită. După șase luni, singurul răspuns cinstit la „de ce e asta aici” este de obicei o presupunere.
Mai rău, o presupunere greșită nu costă nimic și pare sigură. O regulă pe care nu o înțelege nimeni este o regulă pe care cineva o șterge până la urmă la o curățenie, iar lucrul pe care îl împiedica revine.
De aceea, fiecare regulă de aici spune la ce servește și unde poate fi verificată. Unsprezece dintre liniile de comentariu conțin o dată, douăsprezece conțin o cifră măsurată. Acestea sunt cele două lucruri care îi permit unui cititor viitor să decidă dacă motivul mai este valabil.
Trei care nu ar supraviețui fără comentariul lor
Un cod de limbă care arăta ca o extensie de script. O regulă care bloca fișierele-sursă rămase se potrivea după extensie, iar una dintre extensii era .pl — Perl. Previzualizările designurilor se numesc 2900.pl.svg, unde pl înseamnă poloneză. Fiecare previzualizare în poloneză a început să răspundă cu 403, în timp ce toate celelalte limbi erau în regulă. Comentariul spune acum că pl lipsește intenționat din listă, de ce, și ce s-a măsurat în ce zi. Fără asta, următoarea persoană care face ordine în listă îl pune la loc.
Două comutatoare acolo unde unul pare suficient. Fișierele precomprimate nu trebuie comprimate din nou la ieșire. Configurația setează no-gzip, ceea ce oprește unul dintre cele două compresoare ale serverului. Celălalt recomprima fișierul finalizat, în timp ce antetul anunța în continuare gzip, iar browserele primeau conținut ilizibil. Comentariul explică de ce atât no-gzip cât și no-brotli se află acolo, pentru că eliminarea celui de-al doilea pare o simplă curățenie.
O regulă de interdicție inversată. Regula care blochează copiile de rezervă nu enumeră extensiile interzise. Ea verifică dacă un nume de fișier conține o extensie de cod-sursă care nu se află la final — ceea ce prinde și numele pe care nu le-a inventat încă nimeni. Comentariul enumeră cele cinci nume pe care versiunea evidentă le trata greșit, cu codurile lor de stare. Citită singură, regula pare inutil de ingenioasă; citită împreună cu comentariul, pare singurul lucru care funcționează.
Versiunea generală
Comentariile care repetă codul nu valorează nimic, și toată lumea știe asta. Nu asta sunt acestea. Ele consemnează ceea ce codul nu poate consemna: ce a mers prost, ce s-a măsurat, la ce dată și care a fost alternativa respinsă.
Testul care arată dacă merită scris un comentariu este destul de simplu. Dacă linia de deasupra lui ar fi ștearsă de cineva care nu cunoaște povestea, s-ar strica ceva fără zgomot? Dacă da, scrieți povestea. Dacă nu, nu scrieți nimic.
Trei la unu nu este o țintă. Este ceea ce a produs acest test pe un fișier în care aproape fiecare linie există pentru că ceva anume a mers prost.