Il file di configurazione che si spiega da solo
Il .htaccess di questo server è lungo 478 righe. 98 di esse sono regole. 309 sono commenti.
Tre righe di spiegazione per ogni riga che fa qualcosa. Quel rapporto non era pianificato; è quello che succede quando la regola per scrivere una regola è che il motivo deve stare accanto.
Perché una regola di riscrittura ha bisogno di un paragrafo
Una regola in una configurazione di server è insolitamente ostile a essere letta dopo. È stringata per costruzione, non ha un nome, non la si può percorrere passo passo, e il suo effetto è invisibile finché non si chiede proprio l'indirizzo giusto. Sei mesi dopo, l'unica risposta onesta a „perché sta qui" è di solito una supposizione.
Peggio: sbagliare supposizione costa poco e sembra sicuro. Una regola che nessuno capisce è una regola che prima o poi qualcuno cancella durante una pulizia, e ciò che impediva ritorna.
Perciò ogni regola porta qui a cosa serve e dove lo si può verificare. Undici delle righe di commento portano una data, dodici portano un valore misurato. Sono le due cose che permettono a un lettore futuro di decidere se il motivo vale ancora.
Tre che non sopravvivrebbero senza il loro commento
Un codice di lingua che sembrava un'estensione di script. Una regola che bloccava file sorgente dimenticati agiva sull'estensione, e una di queste era .pl — Perl. Le anteprime dei modelli si chiamano 2900.pl.svg, dove pl sta per polacco. Ogni anteprima polacca ha iniziato a rispondere 403 mentre tutte le altre lingue stavano bene. Il commento ora dice che pl è deliberatamente assente dall'elenco, perché, e cosa è stato misurato in quale giorno. Senza quello, la prossima persona che riordina l'elenco lo rimette dentro.
Due interruttori dove uno sembra bastare. I file precompressi non devono essere compressi di nuovo in uscita. La configurazione imposta no-gzip, che ferma uno dei due compressori del server. L'altro ricomprimeva il file finito mentre l'intestazione annunciava ancora gzip, e i browser ricevevano contenuto illeggibile. Il commento spiega perché ci sono entrambi, no-gzip e no-brotli, perché togliere il secondo sembra riordinare.
Una regola di divieto che è rovesciata. La regola che blocca le copie di sicurezza non elenca estensioni vietate. Chiede se un nome di file contiene un'estensione sorgente che non sta alla fine — e così prende i nomi che nessuno ha ancora inventato. Il commento elenca i cinque nomi su cui la versione ovvia sbagliava, con i loro codici di stato. Leggi la regola da sola e sembra inutilmente furba; leggi il commento e sembra l'unica cosa che funziona.
La versione generale
I commenti che ripetono il codice non valgono niente e lo sanno tutti. Questi non sono quello. Registrano ciò che il codice non può: cosa è andato storto, cosa è stato misurato, in che giorno, e quale alternativa è stata scartata.
La prova per capire se un commento vale la pena di essere scritto è abbastanza semplice. Se la riga sopra venisse cancellata da qualcuno che non conosce la storia, si romperebbe qualcosa in silenzio? Se sì, scrivi la storia. Se no, non scrivere niente.
Tre a uno non è un obiettivo. È ciò che quella prova ha prodotto in un file dove quasi ogni riga esiste perché qualcosa di preciso è andato storto.