ศึกษาเกี่ยวกับการเพิ่มหรือลดความสามารถในการผลิตเอกสารรหัส

หลังจากค้นหามากฉันล้มเหลวในการตอบคำถามพื้นฐานที่เกี่ยวข้องกับการสันนิษฐานว่าเป็นที่รู้จักในโลกการพัฒนาซอฟต์แวร์:

สิ่งที่เป็นที่รู้จัก:

การบังคับใช้นโยบายที่เข้มงวดเกี่ยวกับเอกสารรหัสที่เพียงพอ (ไม่ว่าจะเป็นแท็ก Doxygen, Javadoc หรือเพียงแค่ความคิดเห็นมากมาย) จะเพิ่มส่วนหัวไปยังเวลาที่ใช้ในการพัฒนาโค้ด

แต่:

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

คำถาม:

ต้องใช้เวลาในการพัฒนาเพิ่มเติมเพื่อรับประกันเอกสารดังกล่าวซึ่งชดเชยด้วยผลกำไรที่เพิ่มขึ้นจากการผลิตบนถนน (ในแง่ที่ประหยัดอย่างเคร่งครัด) หรือไม่?

ฉันกำลังมองหากรณีศึกษาหรือคำตอบที่สามารถนำหลักฐานที่เป็นหลักฐานมาสนับสนุนข้อสรุปที่ได้รับ

ขอบคุณล่วงหน้า!

บทความ "สไตล์ Typographic เป็นมากกว่าเครื่องสำอาง" ค่อนข้างเก่า แต่มันน่าสนใจมาก: http://portal.acm.org/citation.cfm?id=78611

เป็นเก่าจะไม่รวมถึงทุกสิ่งที่จินตนาการว่าจะเป็นไปได้วันนี้ แต่มันก็แสดงให้เห็นอย่างชัดเจนว่ารหัสเอกสารไม่ว่า

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

จากนั้นพวกเขาขอให้ทั้งสองกลุ่มปฏิบัติงานบางอย่างกับรหัส (เช่นขยายฟังก์ชั่นค้นหาจุดบกพร่อง ... ) และให้คะแนนในด้านความเร็วและคุณภาพของคำตอบ

เพื่อความสมดุลของกลุ่มพวกเขามีจำนวนผู้เชี่ยวชาญและโปรแกรมเมอร์จูเนียร์เท่ากัน

มันกลับกลายเป็นว่ากลุ่ม B (คนที่มีรายชื่อพิมพ์สวย) ทำคะแนนได้ดีกว่ากลุ่ม A ในการทดสอบจำนวนมาก และในบางกรณีเฉพาะผู้เชี่ยวชาญที่มากที่สุดของกลุ่ม A ที่จัดการได้ดีกว่าโปรแกรมเมอร์รุ่นน้องของกลุ่มบี

บทความกล่าวเพิ่มเติม แต่นี่คือสิ่งที่ฉันสามารถจำได้จากหน่วยความจำ (ฉันควรจะมีบทความที่พิมพ์ที่ไหนสักแห่ง)

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

ฉันไม่สามารถสำรองมันด้วยหลักฐานที่ยากใด ๆ ยกเว้นสามัญสำนึก

ฉันไม่ได้มีการศึกษาใด ๆ ที่จะอ้างถึง แต่ฉันมีกฎง่ายๆ: ถ้าฉันกลับมาที่รหัสของฉันในอีกสองสัปดาห์ต่อมาและไม่สามารถรู้ได้ทันทีว่าฉันทำอะไรมันต้องการความคิดเห็นเพิ่มขึ้นหรือต้องการทำให้ง่ายขึ้น .

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

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

ใน API ใด ๆ ที่ไม่ได้จัดทำเป็นเอกสารเล็กน้อย API ในโค้ดนั้นไม่มีประโยชน์อะไรเลย นี่เป็นเพราะพลังใน API มาจากการทำงานร่วมกันเป็นหน่วยทั้งหมด (ไม่ใช่วิธีการ / วัตถุแต่ละวิธีทำงาน)

ดังนั้นมีประโยชน์มากกว่าเอกสารจริงเป็นเอกสารคล้ายตำราที่อธิบายรูปแบบการใช้งานที่คาดหวังของ API และตัวอย่างของวิธีการแก้ไขสถานการณ์ที่ชัดเจนบางอย่าง (ที่ใช้ส่วนใหญ่ (ไม่ใช่ 100%) ของ API)

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

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

คำแนะนำของฉัน: สอนให้นักพัฒนาซอฟต์แวร์ของคุณทราบถึงวิธีการระบุวิธีการที่สำคัญในการทำเอกสาร (API ที่เป็นทางการหรือไม่เป็นทางการที่ใช้กันทั่วไปวิธีการสตับซับซ้อนหรือลึกลับ) และให้พวกเขาควบคุมตนเอง

(เกี่ยวข้องอย่างใกล้ชิด: มีความสม่ำเสมอมากเกินไปในมาตรฐานการเข้ารหัสหรือไม่ )

^{ขอโทษที่ฉันไม่ได้มีการศึกษาใด ๆ ที่จะอ้างถึง แต่ฉันสงสัยว่านี่เป็นปัญหาที่ความพยายามใด ๆ ในการวัดมันจะส่งผลกระทบต่อผลที่ได้มากเกินไปที่จะสรุปข้อสรุปทั่วไป}

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

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

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

งานน้ำเชื้อในหัวข้อนี้เป็นรหัสที่สะอาด

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

ปัญหาคือว่าคุณประหยัดเวลาหรือไม่ด้วยการบันทึกรหัสของคุณกับนักพัฒนาที่ตามมาทุกคนที่ต้องลองคิดดูว่ามันทำอะไร หากรหัสของคุณผ่านการตรวจสอบโค้ดโดยไม่มีใครถามคำถามเกี่ยวกับสิ่งที่ทำคุณอาจอยู่ในสภาพดี การอธิบายสมมติฐานที่คุณทำเกี่ยวกับอินพุตนั้นไม่ยากเกินไป สมมติว่าวิธีการของคุณใช้วัตถุจำนวนเต็มและส่งกลับวัตถุสตริง int สามารถเป็นโมฆะได้หรือไม่ มีค่า min / max (นอกเหนือจาก integer.MinValue / MaxValue) ไหม? มันสามารถส่งคืนสตริงว่างหรือโมฆะได้หรือไม่? มันโยนข้อยกเว้นใด ๆ ? แน่นอนว่าทุกคนสามารถค้นพบสิ่งเหล่านี้ได้ด้วยการตรวจสอบ แต่ถ้ามีผู้พัฒนารายอื่น ๆ กำลังใช้รหัสของคุณอยู่การประหยัดเวลาสักสองสามนาทีนั้นคุ้มค่ากับเวลาของคุณ นอกจากนี้ยังช่วยให้ผู้ทดสอบทำการสร้างการทดสอบเพื่อยืนยันรหัสของคุณ

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

ดังนั้นรหัสควรมีความเห็นดีมากและควรเป็นรหัสที่มีเอกสารซึ่งไม่ต้องใช้เอกสารภายนอกใด ๆ

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

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

ดูClean CodeและPPPจาก Bob Martin เพื่อการสนทนาที่ลึกซึ้งยิ่งขึ้น