Pse skedari ynë i konfigurimit është kryesisht komente

Skedari .htaccess në këtë server ka 478 rreshta. 98 janë rregulla. 309 janë komente.

Tre rreshta shpjegimi për çdo rresht që bën diçka. Raporti nuk u planifikua; ndodh kur rregulli për të shkruar një rregull kërkon që arsyeja të vendoset pranë tij.

Pse rregulli i rishkrimit kërkon një paragraf

Rregulli në konfigurimin e serverit është veçanërisht i vështirë për t'u lexuar më vonë. Është qëllimisht i ngjeshur, nuk ka emër, nuk mund të ndiqet hap pas hapi dhe efekti është i padukshëm nëse nuk kërkohet pikërisht adresa e duhur. Pas gjashtë muajsh, përgjigjja e vetme e ndershme për „pse është kjo këtu“ zakonisht është hamendësim.

Më keq akoma, hamendësimi i gabuar është i lehtë dhe duket i sigurt. Një rregull që nuk e kupton njeri përfundon i fshirë gjatë pastrimit dhe ajo që pengonte kthehet.

Prandaj çdo rregull këtu ka qëllimin dhe vendin ku mund të kontrollohet. Njëmbëdhjetë rreshta komentesh kanë datë, dymbëdhjetë një shifër të matur. Këto dy gjëra i lejojnë lexuesit të ardhshëm të vendosë nëse arsyeja vlen ende.

Tre rregulla që nuk do të mbijetonin pa komentin e tyre

Një kod gjuhe që dukej si prapashtesë skripti. Rregulli që bllokonte skedarë burimorë të mbetur përputhej me prapashtesën dhe njëra ishte .pl — Perl. Pamjet paraprake të dizajneve emërtohen 2900.pl.svg, ku pl është polonishtja. Çdo pamje paraprake polonisht filloi të kthente 403, ndërsa gjuhët e tjera ishin në rregull. Komenti tani thotë se pl mungon me qëllim nga lista, pse dhe çfarë u mat në cilën ditë. Pa të, personi tjetër që pastron listën e vendos sërish.

Dy çelësa aty ku njëri duket i mjaftueshëm. Skedarët e parakompresuar nuk duhet të kompresohen sërish gjatë dërgimit. Konfigurimi cakton no-gzip, që ndal një nga dy kompresuesit e serverit. Tjetri e rikompresonte skedarin e gatshëm, ndërsa koka ende njoftonte gzip dhe shfletuesit merrnin përmbajtje të palexueshme. Komenti shpjegon pse janë aty si no-gzip ashtu edhe no-brotli , sepse heqja e të dytit duket pastrim.

Një rregull ndalimi i përmbysur. Rregulli që bllokon kopjet rezervë nuk rendit prapashtesa të ndaluara. Pyet nëse emri i skedarit përmban një prapashtesë burimore që nuk është në fund — kështu kap emrat që askush nuk i ka shpikur ende. Komenti rendit pesë emrat që versioni i dukshëm i trajtoi gabim, me kodet e tyre të statusit. Vetëm rregulli duket zgjuarsi e panevojshme; me komentin duket si e vetmja gjë që funksionon.

Versioni i përgjithshëm

Komentet që përsërisin kodin janë pa vlerë dhe të gjithë e dinë. Këto nuk janë të tilla. Regjistrojnë atë që kodi nuk mundet: çfarë shkoi keq, çfarë u mat, në cilën datë dhe cila alternativë u refuzua.

Testi nëse ia vlen të shkruhet komenti është i thjeshtë. Nëse rreshtin sipër e fshin dikush që nuk e di historinë, a prishet diçka në heshtje? Nëse po, shkruajeni historinë. Nëse jo, mos shkruani asgjë.

Raporti tre me një nuk është synim. Është ajo që prodhoi testi në një skedar ku thuajse çdo rresht ekziston sepse diçka konkrete shkoi keq.