वैज्ञानिक सॉफ़्टवेयर को दस्तावेज़ करने के अच्छे तरीके क्या हैं?


44

कई बार, जब मुझे विरासत में मिला है या अन्य लोगों द्वारा लिखे गए वैज्ञानिक कोड (या कभी-कभी, यहां तक ​​कि मेरे अपने काम) का सामना करना पड़ा है, मैंने देखा है कि प्रलेखन या तो विरल है या कोई भी नहीं है। अगर मैं भाग्यशाली हूं, तो मैं जानकारीपूर्ण टिप्पणियां देख रहा हूं। अगर मैं बहुत भाग्यशाली हूं, तो यहां तक ​​कि Doxygen टिप्पणियाँ और एक Doxyfile भी हैं ताकि मेरे पास फ़ंक्शन इंटरफेस और कुछ स्वरूपित HTML परामर्श करने के लिए हो। अगर मैं बेहद भाग्यशाली हूं, तो Doxygen और स्रोत फ़ाइल टिप्पणियों के अलावा एक पीडीएफ मैनुअल और उदाहरण हैं, और मैं खुश हूं, क्योंकि यह मेरे जीवन को बहुत आसान बनाता है।

स्रोत कोड के दस्तावेज़ीकरण में कौन सी जानकारी और उपकरण उपयोगी हैं? उस मामले के लिए, वैज्ञानिक सॉफ़्टवेयर के मामले में उस स्रोत कोड के साथ आने वाले डेटा और परिणामों का दस्तावेजीकरण करने के लिए कौन सी जानकारी और उपकरण उपयोगी हैं?



3
आर में, कोई दस्तावेज़ कोड के लिए roxygen (2) और / या स्वेव का उपयोग कर सकता है और विगनेट्स (मैनुअल) लिख सकता है।
रोमन लुसट्रिक

2
एक उत्कृष्ट उदाहरण सौदा हैI ट्यूटोरियल जो न केवल आपको सिखाता है कि सॉफ्टवेयर का उपयोग कैसे करें बल्कि यह भी कि परिमित तत्व कैसे काम करते हैं।
डेविड केचेसन

मुझे matlab कोड के प्रलेखन को आसान बनाने के लिए M2HTML की सिफारिश की गई थी ।
आर्टेम काज़नाचेव

org-

जवाबों:


45

मुझे लगता है कि वैज्ञानिक सॉफ्टवेयर के लिए प्रलेखन को तीन श्रेणियों में विभाजित किया जा सकता है, यह सभी पूर्ण समझ के लिए आवश्यक हैं। सबसे आसान और सबसे आम व्यक्तिगत विधि प्रलेखन है। इसके लिए कई प्रणालियां हैं। आप उल्लेख Doxygen अजगर है, pydoc , और PETSc में हम अपने पैकेज है बुवाई जो उत्पन्न करता है निम्नलिखित

हालाँकि, सॉफ़्टवेयर के किसी भी टुकड़े के लिए जो एक साधारण उपयोगिता से परे है, आपको एक मैनुअल की आवश्यकता है। यह पैकेज के उद्देश्य का एक उच्च-स्तरीय दृश्य प्रदान करता है, और इसकी विभिन्न कार्यक्षमताएं इस उद्देश्य को प्राप्त करने के लिए कैसे एकीकृत होती हैं। यह एक नए उपयोगकर्ता को उनके कोड को बनाने में मदद करता है, अक्सर उदाहरण के उपयोग के माध्यम से। पेट्सक में, हम मैनुअल के लिए लाटेक्स का उपयोग करते हैं, लेकिन पाइक्लाव पैकेज स्फिंक्स फ्रेमवर्क का उपयोग करता है जिससे मैं बहुत प्रभावित हूं। एक चीज जो हमने बुवाई पैकेज में लागू की है जो मुझे बहुत उपयोगी लगती है वह है उदाहरण कोड और फ़ंक्शन प्रलेखन के बीच की कड़ी। उदाहरण के लिए, यह उदाहरणब्रतु समीकरण को हल करता है। ध्यान दें कि आप किसी भी कस्टम प्रकार या फ़ंक्शन कॉल के लिंक का अनुसरण कैसे कर सकते हैं और निम्न-स्तर के दस्तावेज़ के लिए प्राप्त कर सकते हैं, और उन पृष्ठों का उपयोग करके उदाहरणों से कैसे लिंक करते हैं। इस तरह से मैं नई कार्यक्षमता के बारे में सीखता हूं जो परियोजना में अन्य लोगों का योगदान है।

प्रलेखन का एक अक्सर अनदेखा हिस्सा, मुझे लगता है, डेवलपर प्रलेखन है। कोडिंग-शैली के दस्तावेज़ को प्रकाशित करना और रिपॉजिटरी के साथ बातचीत करने के लिए निर्देश प्रकाशित करना असामान्य नहीं है। हालांकि, कार्यान्वयन से पहले किए गए डिजाइन निर्णयों की व्याख्या करना बहुत दुर्लभ है। इन फैसलों में हमेशा व्यापार शामिल होता है, और हार्डवेयर और एल्गोरिदम के संबंध में स्थिति समय के साथ बदल जाएगी। विशेष रूप से डिजाइन निर्णयों के लिए किए गए व्यापार की समीक्षा और औचित्य की चर्चा के बिना, बाद में प्रोग्रामर को पूरी प्रक्रिया को अपने दम पर फिर से बनाने के लिए छोड़ दिया जाता है। मुझे लगता है कि यह सफल रखरखाव और पुराने कोड के सुधार के लिए एक प्रमुख बाधा है जब मूल डेवलपर्स अब प्रभारी नहीं हैं।


स्फिंक्स के लिए +1! ध्यान दें कि इसमें ऑटोडोक शामिल है , जो मुझे लगता है कि पाइडोक से बहुत बेहतर है।
डेविड केचेसन

3
इंटरफ़ेस / उपयोगकर्ता / डेवलपर प्रलेखन में अलगाव के लिए +1।
फ्लोरियन ब्रूकर

19

इन-कोड प्रलेखन

सबसे महत्वपूर्ण बात यह है कि आपके चुने हुए विकास के माहौल में प्रलेखन सुविधाओं का उपयोग करना है, इसलिए इसका अर्थ है कि python के लिए pydoc , जावा में javadoc या C # में xml टिप्पणियाँ । ये कोड लिखने के साथ ही दस्तावेज़ लिखना आसान बनाते हैं।

यदि आप बाद में वापस आने और चीजों के दस्तावेजीकरण पर भरोसा करते हैं, तो आप इसके आस-पास नहीं पहुंच सकते हैं, लेकिन यदि आप इसे वैसे ही कर रहे हैं जैसे आप कोड लिख रहे हैं, तो आपको जो दस्तावेज बनाने की आवश्यकता है वह आपके दिमाग में ताजा होगी। यदि XML डॉक्यूमेंट वास्तविक कोड के साथ अपूर्ण या असंगत है तो C # में भी संकलन चेतावनी जारी करने का विकल्प है।

प्रलेखन के रूप में परीक्षण

एक अन्य महत्वपूर्ण पहलू अच्छा एकीकरण और इकाई परीक्षण है।

अक्सर दस्तावेज़ीकरण इस बात पर ध्यान केंद्रित करता है कि किस वर्ग और विधियां अलगाव में हैं, आपकी समस्या को हल करने के लिए उन्हें एक साथ कैसे उपयोग किया जाता है। टेस्ट अक्सर उन्हें संदर्भ में दिखाते हैं कि वे एक-दूसरे के साथ कैसे बातचीत करते हैं।

इसी तरह, यूनिट-परीक्षण अक्सर बाहरी निर्भरता को स्पष्ट रूप से इंगित करते हैं जिसके माध्यम से चीजों को मॉक एड आउट करने की आवश्यकता होती है ।

मुझे यह भी पता चलता है कि टेस्ट-संचालित विकास का उपयोग करके मैं सॉफ्टवेयर लिखता हूं जो उपयोग करना आसान है, क्योंकि मैं इसे शब्द से सही उपयोग कर रहा हूं। एक अच्छे परीक्षण ढांचे के साथ, कोड को परीक्षण करना आसान बना देता है और इसका उपयोग करना आसान बना देता है।

उच्च स्तरीय प्रलेखन

अंत में सिस्टम स्तर और वास्तु प्रलेखन के बारे में क्या करना है। कई ऐसे दस्तावेज़ को विकी में लिखने या वर्ड या अन्य वर्ड प्रोसेसर का उपयोग करने की वकालत करेंगे, लेकिन मेरे लिए इस तरह के प्रलेखन के लिए सबसे अच्छी जगह कोड के साथ, एक सादे पाठ प्रारूप में है जो संस्करण नियंत्रण प्रणाली के अनुकूल है।

इन-कोड डॉक्यूमेंटेशन की तरह ही, यदि आप अपने कोड रिपॉजिटरी में अपने उच्च स्तर के डॉक्यूमेंट को स्टोर करते हैं, तो आपको इसे अपडेट रखने की संभावना है। आपको यह भी लाभ मिलता है कि जब आप कोड के संस्करण XY को निकालते हैं, तो आपको प्रलेखन के XY संस्करण भी मिलते हैं। इसके अलावा, यदि आप वीसीएस के अनुकूल प्रारूप का उपयोग करते हैं, तो इसका मतलब है कि यह आपके कोड की तरह ही अपने दस्तावेज़ों को शाखा, अंतर और मर्ज करना आसान है।

मैं काफी हद तक reStructuredText (rst) को पसंद करता हूं , क्योंकि यह स्फिंक्स का उपयोग करके html पन्नों और पीडीएफ दस्तावेजों दोनों का उत्पादन करना आसान है , और LaTeX की तुलना में बहुत अधिक मित्रवत है , फिर भी जब आप उन्हें ले सकते हैं तब भी LaTeX गणित के भाव शामिल कर सकते हैं।


मैं कोड के लिए दस्तावेज का समर्थन करने के लिए दस्तावेज़ लिखने के लिए Lyx( lyx.org ) को इंगित करना चाहूंगा LaTeX
ja72

मैंने पिछले समय में Lyx का उपयोग किया है, लेकिन मुझे जो चीज़ पसंद है rst, वह यह है कि मैं इसे एक सामान्य टेक्स्ट एडिटर में लिख सकता हूं (उसी आईडीई में मैं कोड लिखने के लिए उपयोग करता हूं) और अभी भी मुझे पूरा यकीन है कि मुझे पता है कि अंतिम दस्तावेज़ क्या दिखेगा पसंद। इसके अलावा, प्रारूपण सम्मेलनों ने इसे VCS के अनुकूल बनाया, जो कि मेरे लिए महत्वपूर्ण है।
मार्क बूथ

15

फहीम की लगभग हर बात पर मुझे आपत्ति होगी । विशेष रूप से:

1 / "मुझे लगता है कि वैज्ञानिक डेवलपर्स से अपने सॉफ़्टवेयर का दस्तावेजीकरण करने में बहुत समय बिताने की उम्मीद करना अवास्तविक है"। यह एक विफल परियोजना के लिए एक नुस्खा है जो जल्द ही कोई भी उपयोग करने में सक्षम नहीं होगा जिसके पास प्राथमिक डेवलपर्स तक पहुंच नहीं है। यह अच्छे कारण के लिए है कि बड़े वैज्ञानिक कंप्यूटिंग पुस्तकालयों (जैसे PETSc, या deal.II) का व्यापक प्रलेखन है जो 1,000 पृष्ठों या उससे अधिक में चलता है। यदि आपके पास व्यापक दस्तावेज़ नहीं हैं, तो आपके पास एक बड़ा उपयोगकर्ता समुदाय नहीं हो सकता है। हालाँकि, मैं सहमत हूँ कि उदाहरण कोड को सरल और एकल अवधारणा पर ध्यान केंद्रित करने की आवश्यकता है।

2 / "लेखकों को उचित होने पर प्रकाशन के लिए एक पेपर लिखने पर विचार करना चाहिए"। व्यवहार में यह अक्सर संभव नहीं है। एक अवधारणाओं और एल्गोरिदम पर कागजात लिख सकता है, लेकिन इंटरफ़ेस और अन्य डिजाइन निर्णयों पर नहीं। ऐसे पत्रों के पाठकों को यह पता चल जाएगा कि कार्यान्वयन क्या करता है; कार्यान्वयन के उपयोगकर्ताओं को यह जानने की आवश्यकता होगी कि कार्यों को कॉल करने के लिए, तर्कों का अर्थ क्या है, आदि। एक उपयोगकर्ता के रूप में, एक व्यक्ति ज्यादातर समय पूर्व के बिना रह सकता है और बस एक पुस्तकालय को एक ब्लैक बॉक्स के रूप में मानता है, लेकिन कोई भी इसके बिना नहीं कर सकता है इंटरफ़ेस जानकारी।


1
आपका स्वागत है, वोल्फगैंग; मुझे लगता है कि आप इस प्रश्न का उत्तर देने के लिए सही व्यक्ति हैं, लेकिन मेरा एक सुझाव है: आपने जो यहां लिखा है, वह शायद खुद फहीम के उत्तर पर टिप्पणी होना चाहिए, न कि प्रश्न के उत्तर के बजाय।
डेविड केचेसन

मैं वास्तव में अब देख रहा हूं। मुझे लगता है कि मुझे उस समय एहसास नहीं हुआ था कि यह कैसे काम करता है।
वोल्फगैंग बैंगर्थ

@WolfgangBangerth: आपकी टिप्पणियों के लिए धन्यवाद, जो मैंने नहीं देखा क्योंकि मुझे सूचित नहीं किया गया था। मुझे लगता है कि शायद फहीम के सामने @ ने ऐसा किया होगा, लेकिन मेरे पास अच्छा संदर्भ नहीं है। मैं अपने उत्तर में आपकी टिप्पणियों को संबोधित करने का प्रयास करूंगा - एक टिप्पणी में पर्याप्त जगह नहीं है।
फहीम मीठा

@FaheemMitha: क्या आपने उत्तर लिखा है? एक सवाल के नए जवाब के साथ समस्या यह है कि वे कितने अप /
डाउनवोट्स के

@WolfgangBangerth - यह ठीक इसी कारण से है कि किसी उत्तर को ठीक से संदर्भित करने के लिए अच्छा अभ्यास है तो आप उसका उल्लेख करते हैं। यह बहुत जल्दी और सरल है, बस उत्तर पर जाएं, लिंक पर क्लिक करें, फिर लघु लिंक की प्रतिलिपि बनाएँ, आप अपना उत्तर दें, उस पाठ का चयन करें जिसे आप लिंक में बनाना चाहते हैं (जैसा कि मैंने आपके लिए किया था), हाइपरलिंक पर क्लिक करें बटन और पेस्ट लिंक में। फिर कोई भी आपके द्वारा संदर्भित उत्तर पर जल्दी से जा सकता है, चाहे वह आपके स्वयं के उत्तर से अधिक या कम मतदान हुआ हो।
मार्क बूथ

9

यह अच्छा प्रश्न है। पहले सन्निकटन के लिए, कोड को स्व दस्तावेज होने का प्रयास करना चाहिए। तो, उदाहरण के लिए, यदि सॉफ्टवेयर कमांड लाइन है, तो आप ऐसा करने में सक्षम होना चाहिए executable --helpया executable -hया यहाँ तक कि executable(निष्पादन योग्य कोई तर्क के साथ कुछ नहीं करता है तो), और एक संक्षिप्त उपयोग संदेश मुनाफा होता है।

दूसरा, मुझे लगता है कि वैज्ञानिक डेवलपर्स से अपने सॉफ़्टवेयर का दस्तावेजीकरण करने में बहुत समय व्यतीत करने की अपेक्षा करना अवास्तविक है, इसलिए मेरा सुझाव है कि इसे सरल रखें। बुनियादी तरीकों और विकल्पों के साथ एक लघु पाठ मैनुअल और काम कर रहे और परीक्षण किए गएउपयोग के उदाहरण, सरल से अधिक जटिल में स्नातक किए गए (उपयोग के उदाहरण बहुत महत्वपूर्ण हैं और अक्सर उपेक्षित होते हैं) कुछ भी नहीं की तुलना में काफी बेहतर है और अधिकांश वैज्ञानिक सॉफ़्टवेयर ऑफ़र से बहुत अधिक है। मैं उपयोग उदाहरणों के बारे में एक पालतू जानवर का जोड़ा भी चाहूंगा। सरल का अर्थ है सरल। इसका मतलब है कि यदि आप किसी विधि को चित्रित करने की कोशिश कर रहे हैं, तो आप पाठक को भ्रमित करने के लिए दस बाहरी अवधारणाओं या विधियों में नहीं जोड़ते हैं। इसे सरल रखें और एनोटेट करें ताकि पाठक जानता है कि उदाहरण क्या करना चाहिए। मैं यह भी सुझाव देता हूं कि मैन्युअल उपयोग के उदाहरणों को किसी टेस्ट सूट में बांधना चाहिए ताकि कोड बदलने पर वे काम करते रहें। मैं वास्तव में यह नहीं जानता कि यह कैसे करना है, इसलिए कृपया मुझे शिक्षित करने के लिए स्वतंत्र महसूस करें। यदि डेवलपर्स अधिक फैंसी प्राप्त करना चाहते हैं, तो सुनिश्चित करें कि वे अच्छी मार्कअप भाषाओं का उपयोग कर सकते हैं और आगे, मैन पेज और इतने पर जोड़ सकते हैं।

तीसरा, लेखकों को प्रकाशन के लिए एक पेपर लिखने पर विचार करना चाहिए यदि उपयुक्त हो। यह आमतौर पर डिजाइन निर्णयों को संबोधित करता है और मैनुअल करता है की तुलना में सॉफ्टवेयर पर अधिक उच्च स्तरीय परिप्रेक्ष्य देता है, या करने की उम्मीद की जा सकती है। यह उन डिज़ाइन निर्णयों के दस्तावेज़ीकरण को संबोधित करेगा जो @Matt के बारे में बात कर रहे थे।

बेशक, सभी का सबसे महत्वपूर्ण दस्तावेज स्वयं कोड है, जिसे आवश्यक रूप से टिप्पणी की जानी चाहिए। यह मानता है कि कोड मुफ्त सॉफ्टवेयर है। यदि यह नहीं है, तो यह वैज्ञानिक सॉफ्टवेयर के रूप में काफी कम उपयोगी है (क्या आप वास्तव में एक ब्लैक बॉक्स का उपयोग करना चाहते हैं, जहां आप यह नहीं देख सकते कि तरीकों को कैसे लागू किया जाता है?) और मैं एक के लिए इसका उपयोग नहीं करेगा।


5

डेटा और परिणामों को कैसे दस्तावेज़ित करें, इस बारे में आपके प्रश्न का समाधान करने के लिए, मैं पायथन के सिद्धांत मॉड्यूल की तरह कुछ सुझाऊंगा । यह आपको इस तरह से ट्यूटोरियल या परीक्षण लिखने की अनुमति देता है जो स्वचालित रूप से मान्य हो सकते हैं।


5

यदि आप साक्षर प्रोग्रामिंग में रुचि रखते हैं, तो org-babel पर एक नज़र डालें । यह एमएसीएस में ओआरजी-मोड का हिस्सा है और इस तरह से आपको प्रलेखन के लिए निर्यात विकल्पों (लाटेक्स, पीडीएफ, एचटीएमएल, ओडीटी) की एक विस्तृत श्रृंखला मिलती है। एमएसीएस बफर के अंदर की छवियों को प्रदर्शित कर सकता है और आपको लाटेक्स सिंटैक्स में गणितीय समीकरण लिखने देता है ताकि आपको अपने आप को सादे पाठ प्रलेखन में सीमित न करना पड़े।


1
Org- मोड की एक प्रासंगिक विशेषता यह है कि यह सी, एसक्यूएल, बैश, आर, पायथन और कई अन्य भाषाओं को निष्पादित करता है, मूल पाठ में।
डेविड लेबॉउर

1

प्रलेखन जो आपके स्रोत कोड से स्वचालित रूप से प्राप्त होता है, अप-टू-डेट यानी सही दस्तावेज होने में एक आवश्यक घटक है। मैं यह नहीं आंक सकता कि मैंने कितनी बार दस्तावेज़ीकरण देखा है जो स्रोत कोड के पीछे वर्षों से है क्योंकि दस्तावेज़ के प्रति डेवलपर की उदासीनता। इसका आसान उपाय यह है कि प्रोग्रामर के लिए एक ही समय में एक ही स्थान पर नए कोड के साथ-साथ डॉक्यूमेंटेशन लिखना आसान हो जाए, बजाय इसके कि कुछ पोस्टीरियर प्रयास जो अनिवार्य रूप से अधिक गौरवशाली गतिविधियों के पक्ष में डी-प्राथमिकता हो जाएंगे।

यदि चुनने के लिए मजबूर किया गया है, तो मेरे पास विस्तृत और सटीक (यानी वर्तमान) स्रोत कोड टिप्पणियां होंगी लेकिन कोई भी उपयोगकर्ता मैनुअल नहीं है जो किसी गलत उपयोगकर्ता जानकारी से भरा है।


0

पायथन में उपकरण pep8 और pep257 हैं जो गुम या विकृत प्रलेखन की रिपोर्ट करेंगे। Emacs के लिए elpy भी लापता प्रलेखन के बारे में शिकायत करेंगे। Numpy सम्मेलनों docstring reStructuredText साथ पालन करने के लिए अच्छा है। Pep8, pep257 और doctest के साथ टेस्ट py.test और टॉक्सिक के साथ स्वचालित रूप से सेटअप किया जा सकता है।

हमारी साइट का प्रयोग करके, आप स्वीकार करते हैं कि आपने हमारी Cookie Policy और निजता नीति को पढ़ और समझा लिया है।
Licensed under cc by-sa 3.0 with attribution required.