มันถือว่าการปฏิบัติที่ไม่ดีในการรวมหมายเลขบั๊กในชื่อเมธอดสำหรับวิธีแก้ปัญหาชั่วคราวหรือไม่?

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

การรวมหมายเลขข้อผิดพลาดภายในชื่อวิธีการสำหรับวิธีแก้ปัญหาชั่วคราวจะถือเป็นการปฏิบัติที่ไม่ดีหรือไม่

ฉันจะไม่ตั้งชื่อวิธีที่เพื่อนร่วมงานของคุณแนะนำ ชื่อเมธอดควรระบุว่าวิธีการทำอะไร ชื่อชอบPerformSqlClient216147Workaroundไม่ได้ระบุว่ามันทำอะไร หากมีสิ่งใดให้ใช้ความคิดเห็นที่อธิบายวิธีการที่จะพูดถึงว่ามันเป็นวิธีการแก้ปัญหา สิ่งนี้อาจมีลักษณะดังนี้:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

ฉันเห็นด้วยกับMainMaว่าข้อผิดพลาด / หมายเลขข้อบกพร่องไม่ควรปรากฏในซอร์สโค้ดเอง แต่เป็นการแสดงความคิดเห็นในการควบคุมซอร์สเนื่องจากเป็นเมตาดาต้า แต่ไม่น่ากลัวหากพวกเขาปรากฏในความคิดเห็นของซอร์สโค้ด ไม่ควรใช้หมายเลขข้อบกพร่อง / ข้อบกพร่องในชื่อเมธอด

ไม่มีอะไรถาวรกว่าการแก้ไขชั่วคราวที่ใช้งานได้

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

สิ่งที่เขาเสนอคือหลักฐานที่น่าสนใจว่าระบบ QC และ QA ของคุณมีข้อบกพร่องอย่างมาก การติดตามข้อบกพร่องและการแก้ไขข้อบกพร่องอยู่ในระบบติดตามข้อบกพร่องไม่ใช่ซอร์สโค้ด การติดตามการเปลี่ยนแปลงซอร์สโค้ดอยู่ในระบบควบคุมซอร์ส การอ้างอิงโยงระหว่างระบบเหล่านี้อนุญาตให้ติดตามข้อบกพร่องไปยังซอร์สโค้ด .....

ซอร์สโค้ดมีไว้สำหรับวันนี้ไม่ใช่เมื่อวานและไม่ใช่พรุ่งนี้ (เช่นคุณไม่พิมพ์ลงในซอร์สที่จะทำในปีหน้า) ...

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

หากไม่ใช่คุณอาจบอกทุกครั้ง 216147ไม่มีเหตุผลในโค้ดเนื่องจากรหัสไม่ได้เชื่อมโยงกับระบบติดตามบั๊ก (เป็นระบบติดตามบั๊กซึ่งเชื่อมโยงกับตัวควบคุมแหล่งที่มา) ซอร์สโค้ดไม่ใช่แหล่งที่ดีสำหรับการอ้างอิงถึง bug tickets และ version และถ้าคุณต้องการใส่การอ้างอิงเหล่านั้นที่นั่นให้ทำในคอมเม้นท์

โปรดทราบว่าแม้ในความคิดเห็นหมายเลขข้อบกพร่องเพียงอย่างเดียวก็ไม่ได้มีค่ามาก ลองนึกภาพความคิดเห็นต่อไปนี้:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

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

สรุป: คุณไม่ทราบว่าบั๊กนี้เกี่ยวกับอะไร

รหัสเดียวกันสามารถเขียนในวิธีที่แตกต่างกันเล็กน้อย:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

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

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

ด้วยระบบติดตามบั๊กที่หมายเลขระบุปัญหาโดยเฉพาะและเมื่อคุณดึงบั๊กนั้นในระบบจะให้รายละเอียดทั้งหมดที่คุณต้องการ นี่เป็นสิ่งที่ฉลาดมากที่ต้องทำในซอร์สโค้ดและจะช่วยประหยัดเวลานักพัฒนาในอนาคตเมื่อพยายามที่จะเข้าใจว่าทำไมการเปลี่ยนแปลงจึงเกิดขึ้น

หากคุณเห็นชื่อฟังก์ชั่นเหล่านี้จำนวนมากหากซอร์สโค้ดของคุณแสดงว่าปัญหาไม่ใช่หลักการตั้งชื่อของคุณ ปัญหาคือคุณมีซอฟต์แวร์บั๊กกี้

คำแนะนำของเพื่อนร่วมงานของคุณมีคุณค่า มันให้ความสามารถตรวจสอบย้อนกลับได้โดยการเชื่อมโยงการเปลี่ยนแปลงรหัสกับเหตุผลที่บันทึกไว้ในฐานข้อมูลบั๊กภายใต้หมายเลขตั๋วนั้นสาเหตุที่ทำการเปลี่ยนแปลง

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

ฉันคิดว่าทั้งคุณและเขาได้สัดส่วนทั้งหมดนี้แล้ว

ฉันเห็นด้วยกับข้อโต้แย้งทางเทคนิคของคุณ แต่ในตอนท้ายของวันมันจะไม่สร้างความแตกต่างมากนักโดยเฉพาะอย่างยิ่งหากนี่เป็นการแก้ไขชั่วคราวที่สามารถลบออกจาก codebase ในไม่กี่วัน / สัปดาห์ / เดือน

ฉันคิดว่าคุณควรเอาอัตตาของคุณกลับไปที่กล่องแล้วปล่อยให้เขามีวิธีของเขาเอง (ถ้าเขาฟังด้วยฉันจะบอกว่าพวกคุณต้องประนีประนอมกันทั้งคู่กลับเข้าไปในกล่องของพวกเขา)

ทั้งสองวิธีคุณและเขามีสิ่งที่ดีกว่าที่จะทำ

การรวมหมายเลขข้อผิดพลาดภายในชื่อวิธีการสำหรับวิธีแก้ปัญหาชั่วคราวจะถือเป็นการปฏิบัติที่ไม่ดีหรือไม่

ใช่.

ตามหลักการแล้วคลาสของคุณควรแมปกับ / ใช้แนวคิดในโฟลว์ / สถานะแอปพลิเคชันของคุณที่ดีที่สุด ชื่อของ APIs ของคลาสนี้ควรสะท้อนถึงสิ่งที่พวกเขาทำกับสถานะของคลาสเพื่อให้รหัสไคลเอนต์สามารถใช้คลาสนั้นได้อย่างง่ายดาย (เช่นไม่ระบุชื่อที่แท้จริงไม่ได้มีความหมายอะไรนอกจากคุณจะอ่านเฉพาะเจาะจง)

หากส่วนหนึ่งของ API สาธารณะของคลาสนั้นโดยทั่วไปบอกว่า "ดำเนินการ Y ที่อธิบายไว้ในเอกสาร / ตำแหน่ง X" ดังนั้นความสามารถของคนอื่นในการทำความเข้าใจ API จะขึ้นอยู่กับ:

1. พวกเขารู้ว่าจะมองหาอะไรในเอกสารภายนอก

2. พวกเขารู้ว่าจะมองหาเอกสารภายนอกได้ที่ไหน

3. พวกเขาสละเวลาและความพยายามและมองดูจริง ๆ

จากนั้นอีกครั้งชื่อวิธีการของคุณไม่ได้พูดถึงว่า "location X" ตรงไหนสำหรับข้อบกพร่องนี้

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

อย่างน้อยที่สุดหากคุณทราบว่าข้อบกพร่องจะสามารถเข้าถึงได้ในตำแหน่งเดียวกันและสิ่งนี้จะไม่เปลี่ยนแปลง (เช่นหมายเลขข้อบกพร่องของ Microsoft ที่อยู่ที่ URL เดียวกันในช่วง 15 ปีที่ผ่านมา) คุณควรระบุลิงก์ไปยัง ปัญหาในเอกสารประกอบของ API

อย่างไรก็ตามอาจมีวิธีแก้ไขสำหรับข้อบกพร่องอื่น ๆ ที่มีผลต่อ API มากกว่าหนึ่งคลาส คุณจะทำอย่างไร

การมี API ที่มีหมายเลขข้อบกพร่องเดียวกันในหลาย ๆ คลาส ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);ไม่ได้บอกอะไรคุณมากนักและทำให้โค้ดสับสนมากขึ้น

คุณสามารถตัดสินใจว่าข้อบกพร่องอื่น ๆ ทั้งหมดได้รับการแก้ไขโดยใช้ชื่อที่อธิบายถึงการดำเนินการ ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);) ยกเว้นในกรณีของข้อบกพร่อง 216147 ของคุณ (ซึ่งทำลายหลักการออกแบบของ "การจู่โจมน้อย" - หรือถ้าคุณต้องการทำให้เป็นแบบนั้น เพิ่มการวัด "WTFs / LOC" ของรหัสของคุณ)

TL; DR: การปฏิบัติที่ไม่ดี! ไปที่ห้องของคุณ!

เป้าหมายสำคัญของโปรแกรมเมอร์ควรเป็นรหัสที่ใช้งานได้และความชัดเจนของการแสดงออก

การตั้งชื่อวิธีแก้ปัญหา (.... วิธีแก้ปัญหา) ดูเหมือนจะบรรลุเป้าหมายนี้ หวังว่าในบางขั้นตอนปัญหาพื้นฐานจะได้รับการแก้ไขและวิธีการแก้ไขปัญหาจะถูกลบออก

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

หากส่วนหนึ่งของการโต้ตอบกับ SqlClient ต้องการให้คุณแสดงนิพจน์ที่ถูกต้องรหัสของคุณควรอ่าน "performRightExpressionCast ()" คุณสามารถแสดงความคิดเห็นรหัสเพื่ออธิบายสาเหตุได้เสมอ

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

เพื่อนร่วมงานคนหนึ่งของฉันเคยพูดว่า "เมื่อแก้ไขข้อบกพร่องให้สร้างรหัสตามที่ควรจะเป็น" วิธีที่ฉันตีความนั่นคือ "เปลี่ยนรหัสเป็นวิธีที่จะดูว่าข้อผิดพลาดนี้ไม่เคยมีอยู่"

ผลกระทบ:

1. มักจะน้อยรหัสเป็นผล
2. รหัสตรงไปตรงมา
3. การอ้างถึงข้อบกพร่องน้อยลงในซอร์สโค้ด
4. ความเสี่ยงน้อยลงของการถดถอยในอนาคต (เมื่อมีการตรวจสอบการเปลี่ยนรหัสอย่างสมบูรณ์)
5. วิเคราะห์ได้ง่ายขึ้นเนื่องจากนักพัฒนาไม่ต้องแบกภาระกับประวัติการเรียนรู้ที่ไม่เกี่ยวข้องอีกต่อไป

ซอร์สโค้ดไม่จำเป็นต้องบอกฉันว่ามันถึงสถานะปัจจุบันได้อย่างไร การควบคุมเวอร์ชันสามารถบอกประวัติได้ ฉันต้องการซอร์สโค้ดเพื่อให้อยู่ในสถานะที่จำเป็นต่อการทำงาน ที่กล่าวว่าความคิดเห็น "// bug 12345" เป็นครั้งคราวไม่ใช่ความคิดที่ดี แต่มันถูกทารุณกรรม

ดังนั้นเมื่อตัดสินใจว่าจะตั้งชื่อวิธีการของคุณเป็น 'PerformSqlClient216147 วิธีแก้ปัญหา' หรือไม่ให้ถามตัวเองด้วยคำถามเหล่านี้:

1. หากฉันทราบเกี่ยวกับข้อผิดพลาด 216147 ก่อนที่จะเขียนรหัสฉันจะจัดการได้อย่างไร
2. วิธีแก้ปัญหาคืออะไร หากใครที่ไม่เคยเห็นรหัสนี้มาก่อนจะต้องดูมันพวกเขาจะสามารถติดตามมันได้หรือไม่? การตรวจสอบระบบติดตามบั๊กจำเป็นต้องรู้หรือไม่ว่าโค้ดนี้ทำงานอย่างไร?
3. รหัสนี้ชั่วคราวเพียงใด จากประสบการณ์ของฉันมักจะแก้ปัญหาชั่วคราวอย่างถาวรตามที่ @mattnz บ่งชี้