วิธีการที่ดีในการจัดทำเอกสารซอฟต์แวร์ทางวิทยาศาสตร์คืออะไร?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ผมจะใช้เวลาที่มีการคัดค้านเกือบทุกจุดทำให้ Faheem โดยเฉพาะ:

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

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

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

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

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

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

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

หากคุณมีความสนใจในการเขียนโปรแกรมความรู้มีลักษณะที่org-Babel มันเป็นส่วนหนึ่งของโหมดองค์กรใน Emacs และให้ตัวเลือกการส่งออกมากมาย (LaTeX, PDF, HTML, ODT) สำหรับเอกสารประกอบ Emacs สามารถแสดงภาพภายในบัฟเฟอร์และให้คุณเขียนสมการทางคณิตศาสตร์ในรูปแบบ LaTeX เพื่อให้คุณไม่ต้อง จำกัด ตัวเองเป็นเอกสารข้อความธรรมดา

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

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

ใน Python มีเครื่องมือ pep8 และ pep257 ซึ่งจะรายงานเอกสารที่หายไปหรือผิดรูปแบบ elpy สำหรับ Emacs จะบ่นเกี่ยวกับเอกสารที่ขาดหายไป Numpy ประชุม docstringกับ reStructuredText เป็นสิ่งที่ดีที่จะปฏิบัติตาม ทดสอบด้วย pep8, pep257 และ doctest สามารถตั้งค่าได้ด้วย py.test และ tox ทำงานโดยอัตโนมัติ