Kodėl mūsų nuostatų failą daugiausia sudaro komentarai

Šio serverio failas .htaccess yra 478 eilučių ilgio. 98 iš jų yra taisyklės. 309 – komentarai.

Trys paaiškinimo eilutės kiekvienai ką nors darančiai eilutei. Šis santykis nebuvo planuotas; taip nutinka, kai taisyklės rašymo taisyklė reikalauja greta nurodyti priežastį.

Kodėl perrašymo taisyklei reikia pastraipos

Serverio nuostatų taisyklė ypač nepalanki vėlesniam skaitymui. Ji sąmoningai glausta, neturi pavadinimo, jos negalima pereiti žingsnis po žingsnio, o poveikis nematomas, nebent paprašoma tiksliai tinkamo adreso. Po šešių mėnesių vienintelis sąžiningas atsakymas į „kodėl tai čia“ paprastai yra spėjimas.

Dar blogiau, klaidingai spėti pigu ir atrodo saugu. Taisyklė, kurios niekas nesupranta, yra taisyklė, kurią kas nors galiausiai ištrina tvarkydamas, ir tai, nuo ko ji saugojo, grįžta.

Todėl kiekviena taisyklė čia turi paskirtį ir vietą, kur galima patikrinti. Vienuolika komentarų eilučių turi datą, dvylika – išmatuotą skaičių. Šie du dalykai leidžia būsimam skaitytojui nuspręsti, ar priežastis tebegalioja.

Trys, kurios neišliktų be komentaro

Kalbos kodas, atrodęs kaip scenarijaus plėtinys. Likusius pradinio kodo failus blokuojanti taisyklė tikrino plėtinius, ir vienas jų buvo .pl — Perl. Dizainų peržiūros vadinamos 2900.pl.svg, kur pl yra lenkų kalba. Kiekviena lenkiška peržiūra pradėjo atsakyti 403, kai visos kitos kalbos veikė. Komentaras dabar sako, kad pl sąmoningai nėra sąraše, kodėl ir kas kurią dieną išmatuota. Be to kitas sąrašą tvarkantis žmogus jį grąžins.

Du jungikliai, kai vieno atrodo pakanka. Iš anksto suglaudinti failai išsiunčiant neturi būti glaudinami dar kartą. Nuostatos nustato no-gzip, ir tai sustabdo vieną iš dviejų serverio glaudintuvų. Kitas iš naujo suglaudino paruoštą failą, kai antraštė vis dar skelbė gzip, ir naršyklės gavo neperskaitomą turinį. Komentaras paaiškina, kodėl ir no-gzip ir no-brotli yra ten, nes pašalinti antrąjį atrodo lyg tvarkymasis.

Apversta draudimo taisyklė. Atsargines kopijas blokuojanti taisyklė neišvardija draudžiamų plėtinių. Ji klausia, ar failo pavadinime yra pradinio kodo plėtinys, esantis ne pabaigoje, — taip aptinkami dar niekieno nesugalvoti pavadinimai. Komentaras išvardija penkis pavadinimus, kuriems akivaizdi versija suklydo, su jų būsenos kodais. Skaitant vien taisyklę, ji atrodo be reikalo gudri; perskaičius komentarą – vienintelis veikiantis būdas.

Bendroji versija

Kodą atkartojantys komentarai beverčiai, ir tai žino visi. Šie ne tokie. Jie užfiksuoja tai, ko kodas negali: kas nepavyko, kas išmatuota, kurią dieną ir kokios alternatyvos atsisakyta.

Patikra, ar verta rašyti komentarą, pakankamai paprasta. Jei virš jo esančią eilutę ištrintų istorijos nežinantis žmogus, ar kas nors tyliai sugestų? Jei taip, užrašykite istoriją. Jei ne, nieko nerašykite.

Trys su vienu nėra tikslas. Tokį rezultatą ši patikra davė faile, kur beveik kiekviena eilutė yra dėl to, kad kas nors konkretaus nepavyko.