a-philosophy-of-software-design

SKILL.md

---
name: a-philosophy-of-software-design
description: ใช้ในขณะที่เขียน แก้ไข หรือทบทวนโค้ดเมื่อใดก็ตามที่การเปลี่ยนแปลงนั้นเพิ่มชื่อที่ส่งออกหรือนำเข้าได้ สร้างโมดูล คลาส คอมโพเนนต์ ตัวช่วย ฮุก เซอร์วิส หรือวอปเปอร์ รวมศูนย์โค้ดที่ซ้ำกัน หรือเปลี่ยน API กฎของ Ousterhout (โมดูลลึก การซ่อนข้อมูล การลดความซับซ้อน) รวมถึงการทดสอบ invariant สำหรับการแชร์โค้ด การทดสอบต้นทุนของผู้อ่าน และบันทึกการออกแบบที่จำเป็นในตอนท้าย
---

# ปรัชญาการออกแบบซอฟต์แวร์ (John Ousterhout)

## เมื่อใดควรใช้ทักษะนี้

ใช้ทักษะนี้เมื่อคุณออกแบบ เขียน เปลี่ยนแปลง หรือทบทวนโค้ด มันใช้ได้กับการออกแบบโมดูล การเปลี่ยนแปลง API การแยกส่วน การปรับโครงสร้างใหม่ ชื่อ ความคิดเห็น การทดสอบ และงานด้านประสิทธิภาพ ใช้เมื่อการเปลี่ยนแปลงรู้สึกไม่สะดวก หรือเมื่อการเปลี่ยนแปลงหนึ่งกระจายไปหลายไฟล์

## อคติที่ต้องแก้ไข

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

## กฎการตัดสินใจ

- วัดการออกแบบโดยดูว่าลดความซับซ้อนได้มากแค่ไหน เลือกการออกแบบที่ลดภาระของผู้อ่าน ความซับซ้อนมีสี่สัญญาณ การเปลี่ยนแปลงหนึ่งครั้งต้องแก้ไขหลายที่ การพึ่งพาซ่อนอยู่ ขั้นตอนต้องเกิดตามลำดับที่กำหนด ผู้อ่านต้องจำข้อเท็จหลายอย่าง
- ถือว่าการออกแบบเป็นงานต่อเนื่อง แพตช์แรกที่ทำงานได้ไม่ถือว่าสิ้นสุดหากทำให้การเปลี่ยนแปลงในภายหลังยากขึ้น สำหรับการตัดสินใจเกี่ยวกับอินเทอร์เฟซ การแยกโมดูล หรือการนามธรรม ให้เปรียบเทียบการออกแบบสองแบบขึ้นไป
- ชอบโมดูลที่ลึก โมดูลลึกมีอินเทอร์เฟซเล็กและซ่อนความซับซ้อนจำนวนมาก ปฏิเสธบริการผ่านไป ตัวห่อไลบรารีบางๆ และโมดูลช่วยเหลือเล็กๆ ปฏิเสธการแยกที่เพิ่มชื่อแต่ไม่ลดภาระผู้อ่าน
- ออกแบบอินเทอร์เฟซรอบสิ่งที่ผู้เรียกต้องรู้ ไม่ใช่รอบวิธีการทำงานภายใน หลีกเลี่ยงลำดับการตั้งค่าที่เปราะบาง ธงโหมด ปุ่มปรับแต่ง และอาร์กิวเมนต์ที่แสดงตัวเลือกภายใน
- ซ่อนการตัดสินใจที่อาจเปลี่ยนแปลงได้ ตัวอย่างเช่น การแทนค่าภายใน รูปแบบการจัดเก็บ โปรโตคอล รูปแบบไฟล์ และเทคนิคประสิทธิภาพ การบันทึกข้อมูล การทำให้เป็นมาตรฐาน และกรณีขอบเขตเป็นตัวอย่างอื่น เก็บแต่ละอย่างไว้ในโมดูลที่เป็นเจ้าของความรู้นั้น
- ดึงความซับซ้อนลงไปในโมดูลที่เป็นเจ้าของรายละเอียด ยอมรับการใช้งานที่ซับซ้อนขึ้นเมื่อมันให้สัญญาที่ง่ายขึ้นแก่ผู้เรียกและลบงานซ้ำจากแต่ละจุดเรียก
- ทำให้โมดูลทั่วไปในระดับที่เหมาะสม อย่าปรับโมดูลให้เหมาะกับผู้เรียกเพียงคนเดียว อย่าเพิ่มนามธรรมที่คลุมเครือสำหรับความต้องการในอนาคต เก็บกรณีขอบเขตที่หายากออกจากเส้นทางหลัก และวางพฤติกรรมพิเศษไว้ในที่ของมันเอง
- รวมหรือแยกโมดูลโดยพิจารณาจากความซับซ้อนรวม อย่ารวมหรือแยกโดยดูจากขนาด ลำดับการทำงาน ตามนิสัย หรือรูปลักษณ์ เก็บสถานะ พฤติกรรม กฎ และการตัดสินใจที่เกี่ยวข้องไว้ด้วยกัน แยกก็ต่อเมื่อขอบเขตใหม่ลึกกว่าและผู้อ่านสามารถเข้าใจแต่ละด้านได้เอง
- ทำให้ชุดข้อยกเว้นเล็กลง เมื่อเป็นไปได้ เปลี่ยนอินเทอร์เฟซหรือกฎเพื่อไม่ให้สถานะที่ไม่ถูกต้องเกิดขึ้น อย่าทำให้ผู้เรียกทุกคนต้องทำโค้ดป้องกันซ้ำๆ
- ใช้ความคิดเห็นเพื่อลดความซับซ้อน เขียนสัญญาอินเทอร์เฟซ กฎที่ต้องเป็นจริง การตัดสินใจออกแบบที่ซ่อนอยู่และเหตุผลของมัน เขียนข้อเท็จจริงที่ยากที่ผู้เรียกไม่ควรรู้ อย่าทำซ้ำโค้ดในความคิดเห็น อย่าใช้ความคิดเห็นเพื่อปกปิดชื่อที่ไม่ดี การแยกที่ไม่ดี หรือการไหลของการควบคุมที่สับสน
- ถือว่าชื่อ ความสอดคล้อง และความชัดเจนเป็นข้อมูลการออกแบบ ชื่อบอกผู้อ่านถึงนามธรรม ไม่ใช่กลไก การดำเนินการที่เกี่ยวข้องใช้รูปแบบเดียวกัน โค้ดที่ทำให้ผู้อ่านประหลาดใจเพิ่มความซับซ้อน แม้ว่าจะสั้น
- เขียนการทดสอบกับสัญญาสาธารณะและ API ที่เสถียร ทดสอบความซับซ้อนที่ซ่อนอยู่และกรณีพิเศษผ่านสัญญาเหล่านั้น อย่าให้ความง่ายของการทดสอบบังคับอินเทอร์เฟซตื้นหรือรั่ว
- เพิ่มการเปลี่ยนแปลงประสิทธิภาพ รูปแบบ แนวคิด หรือเฟรมเวิร์กด้วยเหตุผลสองอย่างเท่านั้น คือ มันลดความซับซ้อนในฐานรหัสนี้ หรือมีหลักฐานว่าการแลกเปลี่ยนนี้จำเป็น ซ่อนการปรับแต่งแต่ละอย่างไว้หลังอินเทอร์เฟซที่เสถียร

## สัญญาณและการตอบสนองแต่ละอย่าง

- ฟีเจอร์รู้สึกไม่สะดวก หรือการเปลี่ยนแปลงหนึ่งกระจายหลายไฟล์ หรือผู้ทบทวนต้องหาการพึ่งพาที่ซ่อนอยู่ ตอบสนอง: มองหาการซ่อนข้อมูลที่ขาดหายและโมดูลตื้นๆ มองหาขั้นตอนที่ต้องทำตามลำดับ และความซับซ้อนที่ผู้เรียกต้องแบกรับ
- คุณเพิ่มโมดูล ชั้น บริการ ผู้ช่วย ตัวห่อ หรือหน้ากาก หรือเพิ่มรูปแบบ ตัวเลือก คอลแบ็ก หรืออาร์กิวเมนต์ ตอบสนอง: แสดงว่ามันซ่อนความซับซ้อนมากกว่าที่เพิ่ม
- คุณเปลี่ยน API ตอบสนอง: ตรวจสอบสิ่งที่ผู้เรียกปกติควรรู้ ผู้เรียกไม่ควรรู้ลำดับการเรียก การแทนค่า หรือการจัดเก็บ ผู้เรียกไม่ควรรู้การขนส่ง แคช โปรโตคอล หรือรูปแบบไฟล์ ผู้เรียกไม่ควรรู้เวิร์กโฟลว์ภายในหรือขั้นตอนการตั้งค่าหลายขั้น
- คุณเพิ่มกรณีพิเศษ ธง เส้นทางข้อยกเว้น เงื่อนไข หรือคอนเทนเนอร์ที่ผู้เรียกเห็นได้ ตอบสนอง: ถามก่อนว่าโมดูลเจ้าของสามารถทำอะไรแทนได้ มันอาจลบสถานะที่ไม่ถูกต้อง แยกพฤติกรรมผิดปกติ หรือให้การดำเนินการที่แข็งแกร่งกว่า
- คุณแยกโค้ด ดึงฟังก์ชันออก หรือเพิ่มตัวแปร ตอบสนอง: ตรวจสอบว่าขอบเขตหรือชื่อใหม่มีความหมาย มันไม่ควรเพิ่มเพียงการกระโดด สถานะที่ส่งผ่าน หรือขั้นตอนกลางที่ผู้เรียกเห็น
- โค้ดมีเฟสเช่น `prepare` `process` และ `finalize` หรือผู้เรียกต้องสร้างวัตถุเป็นขั้นตอน ตอบสนอง: ตรวจสอบว่าลำดับเวลาคือแนวคิดจริงหรือไม่ ถ้าไม่ใช่ จัดโค้ดรอบความรับผิดชอบที่เสถียร
- ชื่อคลุมเครือ ชื่อกลไก ไม่สอดคล้อง หรือทำให้ผู้อ่านประหลาดใจ ตอบสนอง: คิดใหม่เกี่ยวกับขอบเขตนามธรรม อย่ายอมรับชื่อที่เกือบถูกต้อง
- ความคิดเห็นยาว ทำซ้ำโค้ด อธิบายอินเทอร์เฟซที่สับสน หรือแสดงข้อมูลภายในเพื่ออธิบายการใช้งาน ตอบสนอง: เปลี่ยนนามธรรม หรือย้ายสัญญาที่ขาดหายไปเข้าไปในอินเทอร์เฟซ
- คุณปรับประสิทธิภาพ ตอบสนอง: วัดก่อน แล้วซ่อนการปรับแต่ง อย่ายอมแพ้ความลึกของโมดูลหรือการซ่อนข้อมูลโดยไม่มีหลักฐานว่าการแลกเปลี่ยนจำเป็น
- คุณทดสอบหรือทบทวน ตอบสนอง: ดูพฤติกรรมสาธารณะและสัญญาอินเทอร์เฟซ ดูความซับซ้อนที่ซ่อนอยู่หลัง API ที่เสถียร และกรณีพิเศษที่เก็บไว้หลังนามธรรม

## รายการตรวจสอบสุดท้าย

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

## Gate

ใช้รายการตรวจสอบเต็มรูปแบบเมื่อการเปลี่ยนแปลงเพิ่มชื่อที่โค้ดอื่นสามารถส่งออกหรือนำเข้าได้ ใช้เมื่อการเปลี่ยนแปลงสร้างโมดูล คลาส คอมโพเนนต์ ตัวช่วย hook บริการ หรือ wrapper หรือวางโค้ดที่ทำซ้ำไว้ในที่เดียว การเปลี่ยนชื่อ codemod การเปลี่ยนแปลงการตั้งค่า การเปลี่ยนแปลงข้อมูล และการแก้ไขบรรทัดเดียวไม่จำเป็นต้องใช้

## การทดสอบ invariant: แบ่งปันเฉพาะโค้ดที่เปลี่ยนแปลงพร้อมกัน

- ดึงโค้ดที่ใช้ร่วมกันออกมาเฉพาะเมื่อมันปกป้องกฎที่คุณสามารถตั้งชื่อได้ หลักฐานคือการเปลี่ยนแปลงร่วม: ประวัติแสดงว่าการคัดลอกถูกแก้ไขหรือเปลี่ยนแปลงพร้อมกัน โค้ดที่ดูคล้ายกันแต่เปลี่ยนแปลงแยกกันคือการสัมผัสจังหวะ (rhyme) ปล่อยให้สัมผัสจังหวะเป็นสำเนา บล็อกที่คล้ายกันสามบล็อกไม่พิสูจน์กฎ
- การแก้ไขต้องลบปัญหา ไม่ใช่ย้ายปัญหา การแปลงหกครั้งที่ย้ายไปยังตัวช่วยแปลงทั่วไปหนึ่งตัวยังคงเป็นหกครั้ง เขียนตัวแมปที่มีชนิดที่การแปลงซ่อนอยู่
- เมื่อ abstraction ผิด ให้ใส่โค้ดกลับเข้าไปในบรรทัดและปล่อยให้เกิดการทำซ้ำ อย่าบิดเบือน abstraction ด้วยแฟล็ก
- อย่าแยกโค้ดเพียงเพราะขนาด โมดูลหนึ่งที่มี 400 บรรทัดซ่อนการตัดสินใจหนึ่งอย่างดีกว่าสี่โมดูลที่มี 100 บรรทัดที่รั่วไหลการเชื่อมต่อเดียวกัน
- การอ่านแบบกลไกของ Clean Code หรือ SOLID (ฟังก์ชันเล็กมาก คลาสหนึ่งสำหรับความรับผิดชอบแต่ละอย่าง) ให้โมดูลตื้น ทักษะนี้มีลำดับความสำคัญเหนือแรงกดดันนั้น

## ค่าใช้จ่ายของผู้อ่าน: การทดสอบที่สาม

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

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

ขนาดไฟล์ไม่ได้อยู่ในรายการนี้โดยเจตนา ไฟล์ขนาดใหญ่มากเป็นเหตุผลให้ค้นหาการตัดสินใจที่ซ่อนอยู่ครั้งที่สอง ไม่เคยเป็นเหตุผลในการตัดไฟล์

## ความปลอดภัย

สำหรับโค้ดที่มีอยู่ ให้เขียนการทดสอบที่ยึดพฤติกรรมปัจจุบันก่อน จากนั้นทำให้โมดูลลึกขึ้น สำหรับโค้ดใหม่ ให้เขียนการทดสอบที่กำหนดพฤติกรรมที่ตั้งใจไว้

## หมายเหตุการออกแบบ (จำเป็นเมื่อใช้ gate)

เมื่อใช้ gate ให้ใส่ส่วนหัว `## Design note` ในคำอธิบายของ pull request เขียนสองถึงสี่บรรทัด:

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

ถ้า gate ไม่ใช้ ให้เขียน `## Design note` ตามด้วย `Gate not applicable: <reason>` และใส่หมายเหตุการออกแบบในสรุปของขั้นตอนสุดท้ายของคุณด้วย

## โหมดตรวจสอบ

ใช้ส่วนนี้เมื่อคุณตรวจสอบหรือทดสอบโค้ดที่เอเจนต์หรือคนอื่นเขียน

1. ตรวจสอบหมายเหตุการออกแบบ เมื่อใช้ gate และ pull request ไม่มีส่วน `## Design note` ให้รายงานเป็นข้อบกพร่องที่บล็อก เมื่อหมายเหตุไม่ตรงกับ diff ให้รายงานเป็นข้อบกพร่องที่บล็อก
2. ข้อบกพร่องด้านการออกแบบจะบล็อกก็ต่อเมื่อเป็นไปตามเงื่อนไขทั้งสอง:
   - มันตั้งชื่อกฎของทักษะนี้ กฎคือกฎการตัดสินใจ gate การทดสอบ invariant หรือรายการค่าใช้จ่ายของผู้อ่าน
   - ระบุค่าใช้จ่ายที่ชัดเจนต่อผู้อ่านหรือการเปลี่ยนแปลงถัดไป ตัวอย่าง: "ผู้เรียกต้องรู้รูปแบบการจัดเก็บ" "แนวคิดหนึ่งมีสองชื่อ" "การเปลี่ยนแปลง cap ต้องแก้ไขในสามไฟล์"
3. ทำเครื่องหมายข้อสังเกตการออกแบบอื่นๆ เป็นไม่บล็อก ใส่ในรายการแยกชื่อ "หมายเหตุการออกแบบที่ไม่บล็อก" หมายเหตุที่ไม่บล็อกไม่ส่งงานกลับไปยังผู้สร้าง
4. อย่ารายงานความชอบเป็นข้อบกพร่อง ชื่อ ไฟล์ หรือสไตล์ที่ต่างกันเป็นความชอบ จะกลายเป็นข้อบกพร่องก็ต่อเมื่อมันละเมิดกฎที่ตั้งชื่อและมีค่าใช้จ่ายที่ชัดเจน
5. เมื่อข้อบกพร่องด้านการออกแบบเดียวกันกลับมาในรอบตรวจสอบที่สอง ให้ยกระดับ อย่าขอเปลี่ยนแปลงเดียวกันเป็นครั้งที่สาม

## ทักษะที่เกี่ยวข้อง (เมื่อถูกติดตั้ง)

- `find-shared-code`: การค้นหาเฉพาะรายงานประวัติย้อนหลังสำหรับโค้ดที่ควรแชร์ ใช้การทดสอบ invariant และการทดสอบความลึกของทักษะนี้
- `refactoring` และ `working-effectively-with-legacy-code`: ขั้นตอนที่ปลอดภัยสู่การออกแบบที่ลึกขึ้น ทักษะนี้ตัดสินใจว่าขอบเขตใหม่จะอยู่หรือไม่

## แหล่งที่มาและใบอนุญาต

ทักษะนี้สร้างขึ้นบนกฎ "มินิ" สำหรับ A Philosophy of Software Design ในที่เก็บ ciembor/agent-rules-books บน GitHub (สัญญาอนุญาต MIT, commit 893a88a) ประตู, การทดสอบค่าคงที่, การทดสอบต้นทุนผู้อ่าน, หมายเหตุการออกแบบ และโหมดทบทวน เป็นการเพิ่มเติมจากกฎเหล่านั้น ที่เก็บนี้ยังมีเก็บกฎทั้งหมดของหนังสือด้วย

แท็ก