ระเบียบวิธีสำหรับการบันทึกรหัสฐานที่มีอยู่

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

คำถามของฉันคือ:

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

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

การบันทึกรหัสฐานแบบดั้งเดิม

ฉันขอแนะนำให้ปฏิบัติตามกฎของหน่วยสอดแนมที่มีรหัสดั้งเดิม การพยายามจัดทำเอกสารโครงการมรดกโดยไม่ขึ้นกับการดำเนินการจะไม่เกิดขึ้น

เอกสารในรหัส

สิ่งที่สำคัญที่สุดคือการใช้สิ่งอำนวยความสะดวกเอกสารในสภาพแวดล้อมการพัฒนาที่คุณเลือกดังนั้นนั่นหมายถึงpydocสำหรับ python, javadocในความคิดเห็น java หรือxmlใน C # สิ่งนี้ทำให้ง่ายต่อการเขียนเอกสารในเวลาเดียวกันกับการเขียนรหัส

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

ทดสอบเป็นเอกสาร

อีกด้านที่สำคัญคือมีการรวมที่ดีและการทดสอบหน่วย

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

ในทำนองเดียวกันการทดสอบหน่วยมักจะชี้ให้เห็นการพึ่งพาภายนอกอย่างชัดเจนผ่านซึ่งสิ่งที่จะต้องมีการจำลอง ed ออก

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

เอกสารระดับสูงขึ้น

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

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

ฉันค่อนข้างชอบrstเพราะมันง่ายที่จะสร้างทั้งหน้า html และเอกสาร PDF จากมันและเป็นมิตรกว่าLaTeXมาก แต่ก็ยังสามารถรวมการแสดงออกทางคณิตศาสตร์ของ LaTeXเมื่อคุณต้องการ

คำถามหากิน โดยพื้นฐานแล้วฉันจะใช้วิธี "refactoring" ซึ่งฉันจะพูดซ้ำว่า "ถ้าคุณสัมผัสรหัสให้บันทึกมัน"

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

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

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

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

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

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

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

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

ฉันจะใช้ความคิดเห็น Doxygen Doxygen มีรูปแบบเอาต์พุตมากขึ้นซึ่งเป็นรูปแบบฟรีอื่น ๆ ส่วนใหญ่และง่ายต่อการเรียนรู้

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

อีกเทคนิคทั่วไปคือการกำหนด dev ใหม่ให้กับการบันทึกรหัส จากนั้นให้คนใหม่แต่ละคนผ่านมันไปตามความเร็ว ระวังให้ดีว่า devs บางคนมองสิ่งนี้ว่ารับรูทคลอง - จำเป็นในกรณีโดยตรงเท่านั้น LOL

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

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