ทำไมไฟล์ตั้งค่าของเราส่วนใหญ่เป็นหมายเหตุ

ไฟล์ .htaccess บนเซิร์ฟเวอร์นี้ยาว 478 บรรทัด โดย 98 บรรทัดเป็นกฎ และ 309 บรรทัดเป็นหมายเหตุในโค้ด

คำอธิบายสามบรรทัดต่อหนึ่งบรรทัดที่ทำงาน ไม่ได้วางแผนอัตราส่วนนี้ แต่เกิดขึ้นเมื่อกฎในการเขียนกฎคือเหตุผลต้องอยู่ข้างกัน

ทำไมกฎเขียนเส้นทางใหม่ต้องมีย่อหน้าอธิบาย

กฎในไฟล์ตั้งค่าเซิร์ฟเวอร์ไม่เป็นมิตรต่อการกลับมาอ่านอย่างยิ่ง ตั้งใจเขียนสั้น ไม่มีชื่อ ไล่ทำงานทีละขั้นไม่ได้ และผลมองไม่เห็นเว้นแต่มีคำขอที่อยู่ตรงตามเงื่อนไขพอดี หกเดือนต่อมา คำตอบตรงไปตรงมาเพียงอย่างเดียวของ “ทำไมมีสิ่งนี้อยู่” มักเป็นการเดา

แย่กว่านั้นคือเดาผิดได้ง่ายและดูปลอดภัย กฎที่ไม่มีใครเข้าใจคือกฎที่สักวันใครจะลบตอนจัดระเบียบ และสิ่งที่เคยป้องกันจะกลับมา

กฎแต่ละข้อที่นี่จึงมีคำอธิบายว่ามีไว้ทำอะไรและตรวจได้ที่ไหน หมายเหตุในโค้ดสิบเอ็ดบรรทัดมีวันที่ สิบสองบรรทัดมีตัวเลขที่วัดได้ สองสิ่งนี้ให้ผู้อ่านในอนาคตตัดสินว่าเหตุผลยังใช้ได้หรือไม่

สามกฎที่จะไม่รอดหากไม่มีหมายเหตุในโค้ด

รหัสภาษาที่ดูเหมือนนามสกุลสคริปต์ กฎบล็อกไฟล์ซอร์สที่เหลือจับคู่จากนามสกุล และหนึ่งในนั้นคือ .pl — Perl ภาพตัวอย่างรูปแบบตั้งชื่อเป็น 2900.pl.svgโดย pl คือภาษาโปแลนด์ ภาพตัวอย่างภาษาโปแลนด์ทุกภาพเริ่มตอบ 403 ขณะที่ภาษาอื่นปกติ ตอนนี้หมายเหตุในโค้ดบอกว่า pl จงใจไม่อยู่ในรายการ เพราะอะไร และวัดอะไรในวันไหน หากไม่มี คนถัดไปที่จัดรายการจะใส่กลับ

สวิตช์สองตัวในจุดที่ตัวเดียวดูเพียงพอ ไฟล์ที่บีบอัดล่วงหน้าต้องไม่ถูกบีบอัดอีกขณะส่ง การตั้งค่ากำหนด no-gzipซึ่งหยุดตัวบีบอัดหนึ่งในสองตัวของเซิร์ฟเวอร์ อีกตัวบีบอัดไฟล์สำเร็จซ้ำขณะที่ส่วนหัวยังแจ้ง gzip ทำให้เบราว์เซอร์ได้เนื้อหาที่อ่านไม่ได้ หมายเหตุในโค้ดอธิบายว่าทำไมต้องมีทั้ง no-gzip และ no-brotli เพราะการนำตัวที่สองออกดูเหมือนการจัดระเบียบ

กฎปฏิเสธที่กลับวิธีคิด กฎบล็อกข้อมูลสำรองไม่แสดงรายการนามสกุลต้องห้าม แต่ถามว่าชื่อไฟล์มีนามสกุลซอร์สที่ ไม่ อยู่ท้ายสุดหรือไม่ — ซึ่งจับชื่อที่ยังไม่มีใครคิดได้ หมายเหตุในโค้ดระบุห้าชื่อที่วิธีปกติที่นึกถึงได้ทันทีตรวจผิด พร้อมรหัสสถานะ อ่านกฎอย่างเดียวดูฉลาดเกินจำเป็น แต่พออ่านหมายเหตุในโค้ดก็เหมือนเป็นสิ่งเดียวที่ใช้ได้

หลักทั่วไป

หมายเหตุในโค้ดที่พูดซ้ำโค้ดไม่มีค่า ทุกคนรู้ เรื่องเหล่านี้ไม่ใช่เช่นนั้น แต่บันทึกสิ่งที่โค้ดบันทึกไม่ได้ ว่าอะไรผิด วัดอะไร วันไหน และมีทางเลือกใดที่ไม่ได้เลือก

การทดสอบว่าหมายเหตุในโค้ดควรเขียนหรือไม่ง่ายพอ หากคนที่ไม่รู้เรื่องลบบรรทัดข้างบน จะมีอะไรเสียเงียบ ๆ หรือไม่ หากมีให้เขียนเรื่องราว หากไม่มีอย่าเขียนอะไร

สามต่อหนึ่งไม่ใช่เป้าหมาย แต่เป็นผลที่การทดสอบนั้นให้กับไฟล์ซึ่งแทบทุกบรรทัดมีอยู่เพราะมีบางอย่างผิดจริง