ฉันจะบันทึกโครงสร้างโค้ดที่ซับซ้อนได้อย่างไร


9

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


1
สิ่งนี้จะขึ้นอยู่กับว่ามีใครพูดถึงความซับซ้อนทางคณิตศาสตร์หรือความซับซ้อนทางสถาปัตยกรรม พวกเขาไม่ได้บันทึกไว้ในลักษณะเดียวกัน มันคืออะไร
Edward Strange

2
ที่เกี่ยวข้อง: โปรแกรมเมอร์ควรอธิบายตรรกะเพิ่มเติมที่อยู่เบื้องหลังโค้ดหรือไม่ . ฉันชอบวิธีการทดสอบ -a-a-doc โดยเฉพาะซึ่งแนะนำในคำตอบข้อใดข้อหนึ่ง
ริ้น

1
@Gnat ทำไมขอบคุณ ฉันคิดว่าโดยรวมแล้วคำตอบสำหรับคำถามนั้นจะใช้ได้กับคำถามนี้เช่นกัน
Mark Booth

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

คำตอบ:


8

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

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

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

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


3

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


0

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

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

คุณไม่จำเป็นต้องทำการค้นหาบนเว็บ


1
"ถ้าจำเป็นต้องมี jr. dev เพื่อรักษารหัส ... " จากประสบการณ์ของฉันดีกว่าที่จะสมมติว่าทุกคนที่อ่านความคิดเห็นของคุณคือ jr dev หากพวกเขาไม่ได้พวกเขาจะไม่ได้อ่านความคิดเห็นของคุณ แม้ว่าพวกเขาจะไม่ jr และยังคงอ่านความคิดเห็นศัพท์แสงและสมมติฐานของคุณนำไปสู่การสื่อสารผิดพลาด ในที่สุด ... devs ส่วนใหญ่เช่นเดียวกับสาขาอื่น ๆ ที่มนุษย์รู้จักใช้ชีวิตโดยไม่ให้คำสาปแช่งและไม่เคยได้รับอะไรที่ดีไปกว่า "jr" ทั้งหมด
Edward Strange
โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.