โปรดทำให้คำอธิบายโค้ดเรียบง่าย

 (akselmo.dev)
2 คะแนน โดย GN⁺ 4 시간 전 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • เมื่อมีคำอธิบายยาวและ diff ขนาดใหญ่มาพร้อมกันในการรีวิวโค้ด ผู้ตรวจจะจับประเด็นสำคัญอย่าง เหตุผลของการเปลี่ยนแปลง ได้ยาก ดังนั้นข้อความคอมมิต คำอธิบายใน merge request และคอมเมนต์จึงควรกระชับ
  • คำอธิบายควรโฟกัสที่ ทำไมถึงเปลี่ยน มากกว่าจะเป็นอะไรที่เปลี่ยนไป เพราะรายละเอียดการเปลี่ยนจำนวนมากดูได้จากตัวโค้ดเอง
  • คำอธิบายยาวที่พยายามใส่ทุกบริบทไว้ในครั้งเดียว อาจทำให้ผู้รีวิวบางคนมีสมาธิลดลงและรีวิวได้ช้าลง
  • ในการรีวิวก่อน merge นั้น atomic commit มีความสำคัญเป็นพิเศษ โดยการแก้เล็กน้อยทำได้ด้วย git amend และการเก็บงานให้เรียบร้อยก่อนรวมสามารถทำด้วย rebase หรือ squash
  • ต่อให้ใช้เครื่องมือ LLM ก็ควรเขียนคอมเมนต์ คำอธิบาย และข้อความคอมมิตด้วยตัวเอง เพราะช่วยให้เข้าใจโค้ดและทำให้การรีวิวเข้าถึงได้ง่ายขึ้น

คำอธิบายในการรีวิวควรโฟกัสที่ “ทำไม” มากกว่า “อะไร”

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

ข้อเสนอเกี่ยวกับการจัดระเบียบคอมมิตและการใช้ LLM

  • คอมมิตควรมีความเป็น atomic โดยเฉพาะในการรีวิวก่อน merge และแต่ละการเปลี่ยนแปลงควรทำความเข้าใจได้อย่างอิสระ
  • การแก้เล็กน้อยให้สะท้อนด้วย git amend และก่อนรวมสามารถจัดระเบียบด้วย rebase หรือ squash ได้
  • แม้จะใช้เครื่องมือ LLM ก็ยังมองว่าการเขียนคอมเมนต์ คำอธิบาย และข้อความคอมมิตด้วยตัวเองดีกว่า
    • กระบวนการเขียนด้วยตัวเองช่วยให้เข้าใจสิ่งที่เปลี่ยนแปลงได้ดีขึ้น
    • คำอธิบายที่เขียนเองอาจเข้าถึงผู้รีวิวได้ง่ายกว่า
  • ยังมีความเห็นส่วนตัวร่วมด้วยว่าถ้าเป็นไปได้ก็ควรหลีกเลี่ยงการใช้เครื่องมือ LLM
  • แม้จะมีปฏิกิริยาต่อคำว่า accessibility แต่ใจความสำคัญคือการขอให้คำอธิบายในการรีวิวโค้ดกระชับขึ้นและตรวจทานได้ง่ายขึ้น

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 4 시간 전
ความคิดเห็นจาก Lobste.rs

  • ต้องระวังเมื่อเอา ความต้องการด้านการเข้าถึง ไปเหมารวมว่าเป็นแค่รสนิยมส่วนตัวของใครบางคน
    การมี ADHD ไม่ได้แปลว่าการไม่ชอบ commit message ยาว ๆ เป็นลักษณะร่วมสากลของคน ADHD เสมอไป และเรื่อง accessibility ก็ไม่ใช่การ “ทำทุกอย่างตามที่คนมี ADHD ชอบ” แต่ใกล้เคียงกับการปรับอย่างสมเหตุสมผลโดยไม่สร้างภาระเกินควรให้ผู้ใช้ทั่วไป
    เพราะงั้นฟีเจอร์ด้านการเข้าถึงจำนวนมากจึงถูกวางไว้หลังการตั้งค่าที่แต่ละคนเลือกเองได้ เช่น คอนทราสต์สูง ลดแอนิเมชัน หรือ dark mode

    • น่าจะเขียนให้ชัดกว่านี้ได้ แต่ AuDHD ของฉันต้องการเงื่อนไขบางอย่างเพื่อให้ทำงานและใช้ชีวิตได้ตามปกติ
      ข้อความยาวเป็นก้อน ๆ เช่น คำอธิบายยาวสองหน้า A4 สำหรับการเปลี่ยนแปลงเล็กน้อย อาจขัดขวางการทำงานไปเลย และถ้าฝืนอ่านก็อาจนำไปสู่ภาวะหมดไฟ
      น่าจะควรพูดประมาณว่า “นี่คือความต้องการด้านการเข้าถึงของฉัน และฉันรู้ว่ามีคนคล้าย ๆ กันอีกมาก”
      ถึงอย่างนั้นมันอาจถูกมองว่าเป็นความชอบมากกว่าความจำเป็นก็ได้ แต่ก็อยากขอให้คำนึงถึงคนอย่างฉันด้วยเวลานำกำแพงข้อความที่ LLM สร้างมาแปะใน commit message
    • แต่ละคนไม่เหมือนกัน แต่การบอกว่า “ช่วยพูดประเด็นสำคัญก่อน” นั้นผมมองว่าเป็น ลักษณะสำคัญของ ADHD อยู่พอสมควร
      ในมุมของ accessibility เอง ทุกคนก็ได้ประโยชน์จากการปรับแบบนี้ จึงไม่ค่อยเห็นเหตุผลว่าทำไมต้องคัดค้าน
    • จากประสบการณ์ของฉัน ความลำบากที่ไม่จำเป็นจำนวนมากที่คน neurodivergent และคนพิการต้องเจอ เกิดจากการ มองความต้องการด้านการเข้าถึงว่าเป็นแค่รสนิยม
      เมื่อ accessibility ดีขึ้น แม้แต่คนที่ไม่ได้จำเป็นต้องใช้ฟีเจอร์นั้นเพื่อจะยืนบนเส้นเริ่มต้นเดียวกันก็ยังได้ประโยชน์ไปด้วย ดังนั้นการเดินไปในทิศทางนั้นเป็นเรื่องดี

  • ตั้งแต่ก่อนยุค AI ฉันก็ชอบ คอมเมนต์ที่ละเอียดมาก อยู่แล้ว และคนที่เคยร่วมงานกันมาหลายคนก็มักจะแปลกใจ
    เช่นมีเมธอดนี้: https://github.com/ghostty-org/ghostty/…
    ตลอด 15 ปีที่ผ่านมา ไม่ว่าจะภาษาไหนฉันก็เขียนประมาณสไตล์นี้ และในยุค AI ก็ระบุวิธีนี้ไว้ใน AGENTS.md ด้วย
    ไฟล์และคอมเมนต์ที่ลิงก์ไว้นั้นเขียนโดยมนุษย์ทั้งหมด ไม่ได้ใช้ AI เลย
    เหตุผลง่าย ๆ คือมันบังคับใช้ กฎการบันทึกซ้ำสองทาง ที่ทำให้คอมเมนต์กับโค้ดต้องสอดคล้องกัน
    ถ้าสองอย่างไม่ตรงกัน ก็แปลว่าคอมเมนต์ผิด หรือโค้ดผิด หรือผิดทั้งคู่ และแค่การถามว่า “แล้วอันไหนถูกกันแน่?” ก็ช่วยจับปัญหาได้มากมาย
    สุดท้ายแล้วถ้าเป็นโปรเจกต์ของตัวเอง แต่ละคนจะใส่คอมเมนต์แบบที่ตัวเองต้องการก็คงได้

    • ฉันก็โดนแซวแบบเป็นกันเองบ้างว่า บางทีเขียนคอมเมนต์มากกว่าโค้ด แต่ฉันชอบคอมเมนต์แบบนี้มาก
      เวลากลับมาอ่านโค้ดอีกครั้ง มันช่วยเก็บ บริบทของการตัดสินใจเฉพาะจุด ที่เคยเกิดขึ้นไว้ และยังช่วยทั้ง reviewer และคนที่เพิ่งมาเห็นโค้ดสร้างความเข้าใจบริบทได้ด้วย
      คอมเมนต์แบบนี้แม้จะยาว แต่ไม่ใช่ “รายละเอียดที่ไม่จำเป็น” อย่างที่บทความพูดถึง และตัวอย่างที่ยกมาก็ดูเป็นตัวอย่างที่ดีของคำกล่าวว่า “อธิบายเหตุผล ไม่ใช่อธิบายว่าอะไร”
    • คอมเมนต์แบบนี้ยอดเยี่ยมมาก
      อย่างในตัวอย่าง คอมเมนต์ที่อธิบายว่าทำไมผู้ใช้ macOS ถึงใส่ shell config ไว้ใน ~/.bash_profile และคาดหวังให้เป็น login shell นั้นให้ บริบทที่มีประโยชน์ ว่าทำไมจึงตัดสินใจแบบนั้น
      แต่ถ้ากลับมาที่ LLM โดยส่วนตัวแล้ว ฉันยังไม่เคยเห็นคอมเมนต์ที่ LLM สร้างแล้วมีคุณภาพระดับนั้นเลย
      ส่วนใหญ่ก็แค่พูดซ้ำสิ่งที่เห็นได้ชัดจากโค้ดอยู่แล้ว เช่น ทำ foo() แล้วต่อด้วย bar() และสุดท้ายทำ baz
    • คอมเมนต์แบบที่ลิงก์ไว้นั้นไม่มีปัญหา
      ปัญหาคือความเละเทะจากการแนบ ตารางขนาดใหญ่และรายการหัวข้อย่อยจำนวนมหาศาล ให้กับการเปลี่ยนแปลงเล็กน้อยมาก ๆ
    • รายละเอียดระดับนั้นฉันซาบซึ้งนะ แต่โดยส่วนตัวฉันอยากให้มันไปอยู่ใน commit message ของ commit ที่เพิ่มเมธอดนั้น มากกว่าไปอยู่ในคอมเมนต์
      เพราะ commit message จะคงเป็นบันทึกของช่วงเวลานั้นเสมอ แต่คอมเมนต์อาจค่อย ๆ คลาดเคลื่อนไปตามเวลา
    • คอมเมนต์ที่เริ่มตรงบรรทัด 1467 นั้นเป็นงานชิ้นเอก และสัมผัสถึงความเหนื่อยล้าได้ชัดเจน

  • ที่ทำงานฉันเคยลองเขียนไว้ใน PR template แบบสุภาพว่า “กรุณาอธิบายแรงจูงใจของการเปลี่ยนแปลงนี้และการตัดสินใจเชิงออกแบบสำคัญที่ควรดูในการรีวิวด้วยตัวคุณเอง”
    แต่ 9 ครั้งจาก 10 LLM ที่ใช้อยู่ตอนนั้นจะลบทั้งเทมเพลตทิ้ง แล้วพ่นคำอธิบายยาวเหยียดที่มีทั้งจำนวนเทสต์ที่เพิ่มขึ้น ช่องทำเครื่องหมายว่าผ่านแล้ว และเนื้อหายิบย่อยนอกประเด็นเต็มไปหมด
    เลยทำให้การรีวิวสนุกมากทีเดียว

    • ที่ทำงานฉันก็มีปัญหาเดียวกัน
      ไม่รู้ว่าใครคิดว่าการยัดเครื่องมือสร้าง commit message ด้วย LLM ไว้ทั่วทุกที่เป็นความคิดที่ดี แต่สุดท้ายก็เกิดปัญหา https://noslopgrenade.com/ ขึ้นใน commit
      ใน commit message หรือคำอธิบาย pull request กลับไม่มี บริบทที่มีประโยชน์ อย่างแรงจูงใจของการเปลี่ยนแปลง การตัดสินใจเชิงออกแบบ หรือเหตุผลรองรับ แต่กลายเป็นย่อหน้าที่ยืดรายละเอียดเชิง implementation ซึ่งอ่านจากโค้ดอย่างเดียวก็รู้ได้อยู่แล้ว
    • ฉันก็เคยเห็นพฤติกรรมแบบเดียวกัน
      กำลังคิดว่าจะเพิ่มข้อความใน agents.md ว่า “เวลาเขียน commit message ให้ดู commit-messages.md”
      ใน commit-messages.md ก็คงใส่ แนวทางการเขียน commit message เช่น ห้ามใช้ช่องติ๊กผ่าน/ไม่ผ่านของเทสต์ และให้สรุปผลการทดสอบแทนการไล่รายการทีละรายการ หรือไม่ต้องเขียนเลย

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

    • ฉันก็เหมือนกัน
      บางครั้งก็มีช่วงที่ต้องอธิบายทุกอย่างให้แน่นหนา แต่ทุกวันนี้กลับเห็นแม้แต่การเปลี่ยนชื่อแปรเล็ก ๆ น้อย ๆ ก็ยังมี คำอธิบายขนาดมหึมา แนบมาด้วย

  • ที่น่าสนใจคือ ฉันกลับถูกบอกบ่อยกว่าว่า commit message สั้นเกินไป

    • ประเด็นในบทความนี้อยู่คนละทิศกัน คือวางคู่กันได้กับบทความ Chesterton middle finger ที่บ่นว่าคำอธิบายสั้นเกินไป
    • มันอาจสั้นเกินไปได้ แต่การยัด นิยายทั้งเรื่อง ลงไปก็ไม่สมเหตุสมผลเหมือนกัน
    • LLM เขียนเยอะเกินไปจริง ๆ
      เพราะอย่างนั้นฉันเลยตั้งค่า claude ไม่ให้เขียนคอมเมนต์เด็ดขาด เนื่องจากสุดท้ายฉันต้องมานั่งลบเอง 98% และแม้แต่ 2% ที่เหลือก็ยังต้องเขียนใหม่อยู่ดี

  • ปกติชอบข้อความคอมมิตที่อธิบายละเอียดมาก แต่ก็ชอบจัดวางแบบ โครงสร้างสไตล์บทความข่าว คือเอาข้อมูลที่สำคัญที่สุดไว้ก่อน แล้วค่อยตามด้วยรายละเอียดที่สำคัญน้อยกว่าแต่ยังเกี่ยวข้อง
    ตัวอย่างเช่น ในหัวข้อก็ใส่ข้อมูลที่สำคัญที่สุดให้หนาแน่นที่สุด ย่อหน้าแรกอธิบายสิ่งที่เปลี่ยนไปด้วยประโยคที่บีบอัดน้อยลง และย่อหน้าถัดไปค่อยใส่รายละเอียดเพิ่มเติมที่ไม่จำเป็นต้องอ่านถ้าไม่ได้ยากมากที่จะเข้าใจธรรมชาติของการเปลี่ยนโค้ด
    ดูเหมือนว่าหลายคนจะประเมินความสำคัญของข้อความคอมมิตสำหรับคนที่มาอ่านโค้ดในภายหลังต่ำเกินไป
    เวลาไปคุ้ยโค้ดแล้วสงสัยว่าทำไมบล็อกหนึ่งถึงหน้าตาเป็นแบบนั้น ถ้า git blame พาไปเจอข้อความคอมมิตที่อธิบายอย่างละเอียดมากว่าแนวทางที่ดูงุ่มง่ามนี้จริง ๆ แล้วเป็นตัวเลือกที่เหลืออยู่หลังจากลองหลายวิธีที่ดูดีกว่าแต่ไม่สมบูรณ์ ก็ไม่เคยรู้สึกผิดหวังเลย
    ถ้ากลับมาที่ประเด็นของผู้เขียน การใส่ป้ายบอกอย่างชัดเจนในการสื่อสารเป็นการปรับที่ดีและโดยทั่วไปก็มีประโยชน์
    ในข้อความคอมมิตอาจใส่ประโยคอย่าง “ถ้าคุณกำลังรีวิวโค้ดนี้อยู่ คุณหยุดอ่านตรงนี้ได้เลย” ไว้กลางข้อความได้

  • การพูดว่า “รายละเอียดที่ไม่จำเป็น ถ้าจำเป็นก็ค่อยมาถามได้” เป็นการสมมติอย่างแรงกล้าว่าคนนั้นจะยังอยู่แถวนั้นเสมอ
    ตอนเริ่มมีส่วนร่วมกับ FLOSS codebase ที่มีอายุเกิน 10 ปี ก็เริ่มตั้งใจเขียนข้อความคอมมิตมากขึ้น
    วิธีเดียวที่จะค้นให้เจอมากกว่านี้ว่าทำไมโค้ดถึงเป็นแบบนั้นคือการทำ git archaeology และก็หัดใช้ vc-annonate ของ Emacs เพื่อให้ตามรอยได้ง่าย
    แม้แต่ในโค้ดที่ทำงาน ก็มีหลายครั้งที่ผู้เขียนดั้งเดิมของ codebase ที่ฉันดูแลออกไปนานแล้ว
    ข้อความคอมมิตไม่ได้ถูกอ่านเฉพาะตอนรีวิวเท่านั้น และจริง ๆ แล้ว UI สำหรับรีวิวหลายตัวก็ซ่อนข้อความคอมมิตไว้
    ปัญหาดูจะไม่ใช่ข้อความคอมมิตยาว ๆ เอง แต่ใกล้เคียงกับการเป็น ข้อความคอมมิตที่เขียนไม่ดี มากกว่า
    แนวทางแบบ “ข้อความคอมมิต คำอธิบาย merge request และคอมเมนต์ในโค้ด ควรเขียนให้ชัดเจน ตรงประเด็น ตามความจำเป็น และอธิบายว่าทำไม ไม่ใช่อธิบายแค่ว่าทำอะไร” ดูเป็นแนวทางที่ดี
    ปัญหาอาจเป็นคนที่แต่ก่อนเขียนแค่ว่า Fix Bugz 🚀️ แล้วตอนนี้พอจะทำตาม “แนวปฏิบัติที่ดี” ก็หันไปใช้ LLM เขียนข้อความคอมมิตแทน
    สมมติฐานของฉันคือ สาเหตุที่คนส่วนใหญ่ไม่เขียนข้อความคอมมิตก็เพราะไม่อ่านมัน และที่ไม่อ่านก็เพราะพึ่งพาการดูคอมมิตผ่านที่อย่าง GitHub web interface ทำให้ พลังงานตั้งต้น ในการค้นหามันสูงเกินไป

    • คำว่า “รายละเอียดที่ไม่จำเป็น ถ้าจำเป็นก็ค่อยมาถามได้” เป็นเรื่องของช่วงรีวิว
      ถ้าข้อมูลนั้นสำคัญ ก็สามารถทิ้งไว้เป็นคอมเมนต์หรือเพิ่มลงในข้อความคอมมิตได้
      KDE ใช้ Gitlab มาหลายปีแล้ว

  • ในระยะยาว เพื่อให้ git archaeology กับคนรุ่นหลังทำได้สำเร็จ ก็ต้องมีความสมดุล
    ด้วยการเปลี่ยนคนทำงานและบริบทที่ค่อย ๆ หายไปจากความทรงจำ หลายครั้งต่อมาก็ถามรายละเอียดที่เคยดูไม่จำเป็นนั้นไม่ได้แล้ว
    ช่วงเวลาที่ดีที่สุดในการบันทึกบริบทนั้นก็คือตอนที่เรายังมีมันอยู่
    สิ่งที่ต้องการจริง ๆ อาจเป็นการเอารายละเอียดสำคัญไว้ก่อน และแยกส่วนให้ชัดเจนเหมือนบทสรุปภาพรวม

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

  • การทำให้คำอธิบายโค้ดเรียบง่ายเป็นเรื่องสำคัญ
    เพราะสิ่งที่เข้าใจไม่ได้หรือไม่มีสมาธิพอ จะอ่านไม่ได้
    ในขณะเดียวกัน พอพัฒนาซอฟต์แวร์ไปเรื่อย ๆ บริบทจำนวนมากก็หายไป และตอนนี้บริบทนั้นมักอยู่แค่ในหัวของผู้เขียน คนที่เคยคุยกับผู้เขียน หรือคนที่ดูโค้ดอย่างลึกซึ้ง
    แต่ฉันคิดว่าบริบทนั้นควรถูก ผูกเข้ากับโค้ดให้มากขึ้น ไม่ใช่น้อยลง
    เราไม่ได้คุยกับผู้เขียนได้เสมอไป ดังนั้นควรเขียนมันไว้ในที่ที่เข้าถึงได้ตลอดและอัปเดตไปพร้อมกับโค้ด
    ในกระบวนการพัฒนาส่วนใหญ่ตอนนี้ ที่ที่เหมาะที่สุดสำหรับสิ่งนั้นก็คือข้อความคอมมิตใน git
    การเขียนสรุปไว้ด้านบนนั้นดี แต่ก็อยากแนะนำให้ทิ้งคำอธิบายเพิ่มเติมเกี่ยวกับการเปลี่ยนโค้ดไว้ด้วย
    ถ้าดึงบริบทออกมาไว้ภายนอก แม้แต่เรื่องที่ตอนนี้ยังดูไม่สำคัญ ตัวฉันในอนาคตก็จะขอบคุณเอง
    ต่อไปน่าจะต้องมีวิธีที่ดีกว่าการใส่บริบทไว้แค่ในข้อความคอมมิต และเพราะแบบนั้นส่วนตัวจึงชอบ literate programming ที่ให้พื้นที่มากขึ้นในการอธิบายทั้ง “อะไร” และ “ทำไม” ของโค้ด