Mengapa berkas konfigurasi kami sebagian besar berisi komentar

Berkas .htaccess di server ini panjangnya 478 baris. 98 di antaranya adalah aturan. 309 adalah komentar.

Tiga baris penjelasan untuk setiap baris yang melakukan sesuatu. Rasio itu tidak direncanakan; begitulah hasilnya jika aturan untuk menulis sebuah aturan adalah bahwa alasannya harus ditulis di sebelahnya.

Mengapa aturan rewrite membutuhkan satu paragraf

Aturan dalam konfigurasi server luar biasa sulit dibaca di kemudian hari. Aturan itu ringkas menurut rancangannya, tidak punya nama, tidak bisa ditelusuri langkah demi langkah, dan efeknya tidak terlihat kecuali alamat yang tepat kebetulan diminta. Enam bulan kemudian, satu-satunya jawaban jujur atas “mengapa ini ada di sini” biasanya hanyalah tebakan.

Lebih buruk lagi, menebak dengan salah itu murah dan tampak aman. Aturan yang tidak dipahami siapa pun adalah aturan yang pada akhirnya dihapus seseorang saat merapikan, dan hal yang selama ini dicegahnya muncul kembali.

Jadi setiap aturan di sini membawa keterangan untuk apa aturan itu ada, dan di mana hal itu dapat diperiksa. Sebelas baris komentar memuat tanggal, dua belas memuat angka hasil pengukuran. Itulah dua hal yang memungkinkan pembaca di masa depan memutuskan apakah alasannya masih berlaku.

Tiga aturan yang tidak akan bertahan tanpa komentarnya

Kode bahasa yang tampak seperti ekstensi skrip. Sebuah aturan yang memblokir sisa berkas sumber mencocokkan berdasarkan ekstensi, dan salah satu ekstensinya adalah .pl — Perl. Pratinjau desain diberi nama 2900.pl.svg, dengan pl berarti bahasa Polandia. Setiap pratinjau berbahasa Polandia mulai menjawab 403, sementara semua bahasa lain baik-baik saja. Komentarnya kini menyebutkan bahwa pl sengaja tidak dicantumkan dalam daftar, alasannya, dan apa yang diukur pada hari apa. Tanpa itu, orang berikutnya yang merapikan daftar akan memasukkannya kembali.

Dua sakelar padahal satu tampak cukup. Berkas yang sudah dikompresi sebelumnya tidak boleh dikompresi lagi saat dikirim keluar. Konfigurasinya menetapkan no-gzip, yang menghentikan salah satu dari dua kompresor server. Kompresor yang lain mengompresi ulang berkas yang sudah jadi sementara header masih menyatakan gzip, dan browser menerima konten yang tidak terbaca. Komentarnya menjelaskan mengapa no-gzip dan no-brotli sama-sama ada, karena menghapus yang kedua tampak seperti merapikan.

Aturan penolakan yang dibalik. Aturan yang memblokir salinan cadangan tidak mendaftar ekstensi terlarang. Aturan itu memeriksa apakah sebuah nama berkas mengandung ekstensi sumber yang tidak berada di akhir — sehingga menangkap nama-nama yang belum pernah terpikirkan oleh siapa pun. Komentarnya mencantumkan lima nama yang ditangani secara keliru oleh versi yang paling jelas, beserta kode statusnya. Jika aturannya dibaca sendirian, aturan itu tampak cerdik secara berlebihan; jika komentarnya dibaca, aturan itu tampak sebagai satu-satunya cara yang berhasil.

Versi umumnya

Komentar yang sekadar mengulang kode tidak ada nilainya, dan semua orang tahu itu. Komentar-komentar ini bukan jenis itu. Komentar ini mencatat hal yang tidak bisa dicatat kode: apa yang salah, apa yang diukur, pada tanggal berapa, dan alternatif apa yang ditolak.

Uji untuk menentukan apakah sebuah komentar layak ditulis cukup sederhana. Jika baris di atasnya dihapus oleh seseorang yang tidak tahu ceritanya, apakah sesuatu akan rusak tanpa suara? Jika ya, tuliskan ceritanya. Jika tidak, jangan tulis apa pun.

Tiga banding satu bukanlah target. Itulah hasil uji tersebut pada sebuah berkas yang hampir setiap barisnya ada karena sesuatu yang spesifik pernah salah.