Miks meie konfiguratsioonifail koosneb enamasti kommentaaridest

Selle serveri .htaccess on 478 rida pikk. Neist 98 on reeglid ja 309 kommentaarid.

Kolm selgitusrida iga rea kohta, mis midagi teeb. Seda suhet ei planeeritud; see juhtub siis, kui reegli kirjutamise reegel on, et põhjus peab olema selle kõrval.

Miks ümberkirjutusreegel vajab lõiku

Serverikonfiguratsiooni reegel on hilisemaks lugemiseks ebatavaliselt vaenulik. See on tahtlikult lakooniline, sellel pole nime, seda ei saa samm-sammult läbi käia ja selle mõju on nähtamatu, kui just õiget aadressi ei küsita. Kuue kuu pärast on ainus aus vastus küsimusele „miks see siin on“ tavaliselt oletus.

Veel hullem: valesti oletada on odav ja see näeb ohutu välja. Reegel, millest keegi aru ei saa, on reegel, mille keegi lõpuks korrastamisel kustutab, ja see, mida see takistas, tuleb tagasi.

Seepärast kannab iga siinne reegel seda, milleks see on, ja kus seda saab kontrollida. Üksteist kommentaarirea kannab kuupäeva, kaksteist mõõdetud arvu. Need on kaks asja, mis lasevad tulevasel lugejal otsustada, kas põhjus kehtib veel.

Kolm, mis ei püsiks ilma oma kommentaarita

Keelekood, mis nägi välja nagu skriptilaiend. Reegel, mis blokeeris mahajäänud lähtefailid, sobitas laiendi järgi ja üks laiendeid oli .pl — Perl. Kujunduste eelvaated on nimega 2900.pl.svg, kus pl on poola keel. Iga poolakeelne eelvaade hakkas vastama 403, kuigi kõik muud keeled olid korras. Kommentaar ütleb nüüd, et pl puudub nimekirjast tahtlikult, miks, ja mida mõõdeti mis päeval. Ilma selleta paneb järgmine nimekirja korrastaja selle tagasi.

Kaks lülitit seal, kus üks näib piisav. Eelpakitud faile ei tohi väljamineku ajal uuesti pakkida. Konfiguratsioon seadistab no-gzip, mis peatab ühe serveri kahest pakkijast. Teine pakkis valmis faili uuesti, kuigi päis teatas veel gzipi, ja brauserid said loetamatu sisu. Kommentaar selgitab, miks on vaja nii no-gzip kui ka no-brotli on olemas, sest teise eemaldamine näeb välja nagu korrastamine.

Pööratud keeluereegel. Reegel, mis blokeerib varukoopiad, ei loetle keelatud laiendeid. See küsib, kas failinimi sisaldab lähtelaiendit, mis ei ole lõpus — see püüab kinni ka nimed, mida keegi pole veel välja mõelnud. Kommentaar loetleb viis nime, mida ilmselge versioon valesti sai, koos nende olekukoodidega. Lugege reeglit üksi ja see näeb tarbetult nutikas välja; lugege kommentaari ja see näeb välja nagu ainus, mis töötab.

Üldine versioon

Kommentaarid, mis kordavad koodi, on väärtusetud ja seda teavad kõik. Need ei ole sellised. Need salvestavad selle, mida kood ei suuda: mis läks valesti, mida mõõdeti, mis kuupäeval ja milline alternatiiv tagasi lükati.

Test, kas kommentaar tasub kirjutada, on piisavalt lihtne. Kui selle kohal oleva rea kustutaks keegi, kes lugu ei tea, kas miski läheks vaikselt katki? Kui jah, kirjutage lugu üles. Kui ei, ärge kirjutage midagi.

Kolm ühe vastu ei ole eesmärk. See on tulemus, mille see test andis failis, kus peaaegu iga rida on olemas, sest midagi konkreetset läks valesti.