การจัดทำเอกสารตรรกะทางคณิตศาสตร์ในรหัส

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

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

มีวิธีที่ง่ายและชัดเจนกว่าหรือไม่?

PS การให้ชื่อที่สื่อความหมาย ( timeOfFirstEventแทนt1) กับตัวแปรทำให้โค้ดมีความละเอียดมากขึ้นและอ่านได้ยากขึ้น

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

(ถ้าคุณไม่ได้มีการอ้างอิงดังกล่าว แต่คณิตศาสตร์ของคุณเป็นเสียงและมีประโยชน์บางทีคุณควรพิจารณาการเผยแพร่ด้วยตัวคุณเอง. เพียง sayin'.)

เมื่อฉันต้องใช้อัลกอริทึมเช่นนั้นมีสองสิ่งที่ฉันทำ

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

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

3. จัดทำบทสรุปของอัลกอริทึมในแง่เทคนิค / คณิตศาสตร์และรวมถึงการอ้างอิงภายนอกใด ๆ ที่ฉันรู้ อีกครั้งฉันทำสิ่งนี้ด้วยวิธีการของตัวเองดังนั้นมันจึงมีโอกาสที่ดีกว่าในการรักษาความสัมพันธ์ ข้อความธรรมดาไม่ดีนักในกรณีนี้ดังนั้นฉันจะกล่าวถึงคำศัพท์ทางคณิตศาสตร์อย่างดีที่สุดที่ฉันสามารถทำได้และชี้แจงในความคิดเห็นเกี่ยวกับผู้ปกครองข้างๆ ตัวอย่างเช่น, x^y (x raised to the power y)

4. บันทึกว่าฉันแบ่งขั้นตอนวิธีออกเป็นส่วนต่าง ๆ อย่างไรและระบุว่าแต่ละตัวหมายถึงอะไรในอัลกอริทึม เช่น.t1 is time of first event

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

6. เขียนการทดสอบหน่วยที่จะตรวจสอบการทำงานของอัลกอริทึม

ท้ายที่สุดถ้ามันซับซ้อนจริง ๆ จริง ๆ แล้วฉันก็ลาออกจากการเป็นเจ้าของว่าฉันเป็นเจ้าของรหัสนั้นสำหรับเวลาที่เหลือในโครงการนั้น

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

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

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

2. ให้คำอธิบายสำหรับตัวแปรทั้งหมด อีกครั้งเราใช้ Tex สำหรับสิ่งนั้นหากกระดาษต้นฉบับใช้ตัวอักษรกรีกหรือตัวอักษรอื่น เหตุผลสำหรับเรื่องนี้คือบ่อยครั้งที่เอกสารและหนังสือเพียงพอที่จะใช้สัญลักษณ์ที่แตกต่างกัน หากมีคนต้องการทำงานซ้ำคณิตศาสตร์สิ่งนี้จะทำให้ง่ายขึ้นมาก

3. พยายามเขียนโค้ดสมการหนึ่งชิ้น มันง่ายกว่าที่จะจดจำวิธีนั้น อย่าโพสต์ Tex-Code ของสมการเต็มรูปแบบลงในโค้ด - สมการนั้นสั้นมากและการโพสต์ tex นั้นยุ่งและไม่จำเป็นหรือสมการนั้นใหญ่และรหัส tex นั้นไร้ประโยชน์เว้นแต่คุณจะรวบรวม อ้างอิงแทน) การแยกสมการออกเป็นชิ้นเล็ก ๆ ทำให้ยากที่จะเข้าใจว่าเกิดอะไรขึ้น (ถ้าคุณเก่งคณิตศาสตร์อย่างน้อย)

IMHO การสำนึกที่สำคัญที่สุดคือสูตรมักขึ้นอยู่กับบริบท กระดาษคณิตศาสตร์ทุกเล่มที่ฉันรู้ต้องใช้เวลาในการตั้งค่าสภาพแวดล้อมของแบบจำลอง คุณควรทำเช่นเดียวกัน

ข้อความไม่มีพลังในการแสดงออกทางคณิตศาสตร์

คุณพูดถูก เนื่องจากคุณกำลังมองหาวิธีที่จะทำมันนอกรหัสและ Tex เป็น overkill นอกจากมีเส้นโค้งการเรียนรู้ที่สูงชันคำแนะนำของฉันมีดังนี้:

ใช้ OpenOffice.org/LibreOffice Math Equation Editor

แจกฟรี. มันเปิด.

คุณสามารถใช้ได้ทั้งภาพหรือเขียนสมการในภาษาพิเศษ

คุณไม่ต้องเรียนรู้ภาษาทันทีเพราะเมื่อคุณใช้ GUI ระบบจะสร้าง "รหัส" ในแผงควบคุมเพื่อให้คุณเห็น

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