Diff for "ThaiChangeSetComments"

วิธีการเขียนคำอธิบายเซ็ตการแก้ไขที่ดี

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

เพราะฉะนั้นคุณควรจะมองบรรทัดแรกของคำอธิบายเหมือนกับหัวจดหมาย โดยบรรทัดแรกนี้ควรจะ:

• เป็นบรรทัดที่จบในตัวเอง
• ไม่ยาวมากนัก (ไม่เกิน 65 ตัวอักษรภาษาอังกฤษ)
• อธิบายคร่าวๆเกี่ยวกับเนื้อหาของเซ็ตการแก้ไข

ด้านล่างนี้เป็นตัวอย่างของคำอธิบายที่ดี:

 เวอรชั่นแรกของระบบ veeblefrotzer

 ใช้เทคนิค McWhirly/O'Blivet

 เวอร์ชั่นแสดงผลถูกต้องสำหรับวันที่ 12 ของทุกๆเดือน
 แต่ยังใช้ไม่ได้กับวันอื่นๆ

คำอธิบายด้านบนเป็นตัวอย่างที่ดีเพราะว่า:

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

นี่คือตัวอย่างที่ไม่ค่อยดีนัก:

 เขียนเวอร์ชั่นแรกของระบบ veeblefrotzer ซึ่งใช้วิธี McWhirly/O'Blivet เพื่อ
 envolvolution ของ subducted whingnangle  ลองดู McWhirly, O'Blivet,
 "Acta Exsanguinata", vol. III, chap. 19 สำหรับคำอธิบายเกี่ยวกับเทคนิคนี้
 แบบสั้นๆ  ถ้าหาบทนี้ไม่เจอก็คงเพราะมีคนตัดมันออกมาแล้วเอาไปแปะอยู่ตามผนังของห้อง
 ทำงานที่ไหนซักที่ล่ะ

ทำไมมันถึงไม่ค่อยดีน่ะเหรอ?

• บรรทัดแรกไม่จบในบรรทัด (ต้องอ่านต่อไปยังบรรทัดที่สอง)

• ไม่แบ่งย่อหน้า → ทำให้อ่านยาก

• มีรายละเอียดที่ไม่ค่อยเกี่ยวข้องกับการแก้ไขเยอะ

CategoryHowTo CategoryThai