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