कोड में गणितीय तर्क का दस्तावेजीकरण

Question

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

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

क्या एक सरल और स्पष्ट तरीका है?

---

पीएस चर के लिए वर्णनात्मक नाम (के timeOfFirstEventबजाय t1) वास्तव में कोड को अधिक क्रियात्मक बनाता है और यहां तक ​​कि बहुत कठिन भी पढ़ता है।

Comments

TeX सीखना वास्तव में उतना मुश्किल नहीं है। यदि आपके पास अपना कोड कहीं भी ऑनलाइन है, तो MathJax इसे आधे समय में प्रिंट कर देगा। कृपया याद रखें कि एचएएल / एस जैसी ऐसी भाषाएं हैं जहां आपकी चिंताएं बहुत पहले ही गूंज चुकी हैं।

— हिरण हंटर

अपने स्वयं के सींग को टॉट नहीं करना, लेकिन यहां एक उदाहरण है: meta.stackexchange.com/a/49787/141513 विचार इसे लिखना है ताकि कोई व्यक्ति जो इसे देखता है वह समझ सके कि यह क्या करता है, भले ही वे समझ में न आएं इसके पीछे गणित। अच्छा कार्य- / चर-नाम और एक साधारण टिप्पणी या दो आमतौर पर ऐसा करने के लिए पर्याप्त हैं।

— ब्लूराजा - डैनी पफ्लुगुएफ्ट

यह भी देखें: "टिप्पणियाँ एक कोड गंध हैं"

— gnat

Answer 1

ऐसे हालात में ऐसा करना सही एल्गोरिथ्म, सूत्र या जो कुछ भी साथ लागू करने के लिए है कि वास्तव में प्राथमिक वास्तविक दुनिया स्रोत में के रूप में ही चर नाम (जहां तक प्रोग्रामिंग भाषा इस अनुमति देता है के रूप में), और यह ऊपर एक संक्षिप्त टिप्पणी करते हुए कहा है "लेवेन्शेटिन दूरी अभिकलन" जैसा कुछ वर्णन [नुथ १ ९ ६ "] में वर्णित है, जहां प्रशस्ति पत्र गणित के आसानी से सुलभ वर्णन से जोड़ता है।

(यदि आपके पास ऐसा कोई संदर्भ नहीं है , लेकिन आपका गणित ध्वनि और उपयोगी है, तो शायद आपको इसे स्वयं प्रकाशित करने पर विचार करना चाहिए।

Comments

@JustinC नहीं, मुझे लगता है कि इसका मतलब वही चर नाम है, अगर इसका कहना है कि y = m*x + cआप m, x और c का उपयोग चर

— jk के रूप में करते हैं।

@JustinC मेरा मतलब था: केवल उन चर और स्थिर नामों का उपयोग करें जो प्रकाशन में हैं - आमतौर पर वे एक-अक्षर के नाम जैसे n, f, q या शायद n_i हैं। मैं ओपी से सहमत हूं जो EulerLinearMomentumवास्तव में कम पठनीय है m। मुद्दा यह है कि सूत्रों को व्यक्त करने के लिए स्रोत कोड पसंदीदा माध्यम नहीं है, इसलिए जोर यह सत्यापित करने में आसान होना चाहिए कि कोड मुद्रित सूत्र के समान काम करता है, न कि यह कोड प्रोग्राम की आवश्यकताओं को पूरा करता है।

— किलियन फोथ

मैं उस रणनीति से सहमत होगा; हालाँकि, हम जिस पाठ के बारे में बात कर रहे हैं वह कोड है जिसमें कोड में एक विशिष्ट परिशुद्धता / पैमाने और व्यवहार सहित अंतर्निहित बाधाएं हैं (एक ज्ञात होस्ट या लक्ष्य दिया गया है)। आप गणितीय मॉडल का नमूना या डिजाइन नहीं कर रहे हैं, आप इसे कोड में लागू कर रहे हैं (ज्यादातर मामलों में)। उचित नामों का उपयोग किए बिना, जो वर्णन को सत्यापित करने के लिए बहुत कठिन दर्शाया गया है।

— जस्टिन

+1। यदि संदर्भ हाल के प्रकाशन का है, तो पेपर को डीओआई हाइपरलिंक दें। उदाहरण dx.doi.org/10.1000/182 । यह वही है जो DOI के लिए डिज़ाइन किया गया था - एक प्रकाशन के लिए एक छोटा, मानक URL, कभी नहीं बदलने की गारंटी।

— MarkJ

@KeithS पूरी तरह से निर्भर करता है, एक छोटे समीकरण के लिए जहां हर चर का भौतिक अर्थ ठीक होता है, लेकिन क्या हो अगर आप एक एफएफटी एल्गोरिदम को लागू कर रहे हैं, जहां बिना किसी भौतिक अर्थ के कई आंशिक परिणाम होंगे। इन स्थिति में आप पूरी तरह गणितीय साहित्य मिलान किया जाना चाहिए, क्योंकि यह है डोमेन भाषा

— जे।

Answer 2

जब मुझे उस तरह के एल्गोरिदम को लागू करना पड़ा है, तो कुछ चीजें हैं जो मैं करता हूं।

1. जितना संभव हो, एल्गोरिथ्म को अपनी स्वयं की विधि या अधिमानतः वर्ग के लिए अलग करें। मेरी वर्तमान परियोजना में Mathजटिल एल्गोरिदम को जोड़ने के लिए स्वयं के बराबर वर्ग है।

2. इस बात का एक सारांश प्रदान करें कि एल्गोरिथ्म शब्द के किसी भी सामान्य समिश्रण या शॉर्टहैंड सन्दर्भ सहित क्या करना है। मैं इसे विधि में ही करता हूं, इसलिए यह कोड के साथ रहता है।

3. तकनीकी / गणितीय शब्दों में एल्गोरिथ्म का सारांश प्रदान करें और किसी भी बाहरी संदर्भ को शामिल करें जो मुझे पता है। दोबारा, मैं इसे विधि के साथ करता हूं, इसलिए इसके प्रासंगिक रहने की बेहतर संभावना है। सादा पाठ इस मामले में महान नहीं है, इसलिए मैं गणितीय शब्द का सबसे अच्छा उल्लेख करूँगा जो मैं कर सकता हूं और इसके बगल में एक पैतृक टिप्पणी में स्पष्ट कर सकता हूं। उदाहरण के लिए, x^y (x raised to the power y)

4. दस्तावेज़ कैसे मैं एल्गोरिथ्म को घटकों में अलग कर रहा हूं और इंगित करता हूं कि एल्गोरिथ्म में प्रत्येक चर का प्रतिनिधित्व करता है। जैसे।t1 is time of first event

5. एल्गोरिथ्म को कोड करें और जटिल भागों पर टिप्पणी करें। अनिवार्य रूप से, मैं कहीं भी एक टिप्पणी जोड़ूंगा, मैं एक ऐसा कदम उठाऊंगा जो एल्गोरिथम के भीतर स्पष्ट या सीधा नहीं था। मैं विशेष रूप से सुनिश्चित करता हूं कि मैं किसी भी गैर-स्पष्ट शॉर्टकट पर टिप्पणी करूं और वे ठीक क्यों हैं कि मैं कार्यान्वयन के भीतर ले सकता हूं।

6. कुछ यूनिट परीक्षण लिखें जो एल्गोरिथ्म के संचालन को मान्य करेगा।

अंत में, यदि यह वास्तव में है, वास्तव में, वास्तव में जटिल है तो मैं अपने आप को इस तथ्य से इस्तीफा दे देता हूं कि मैं उस परियोजना के शेष समय के लिए उस कोड का स्वामी हूं।

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

Answer 3

हमारी परियोजनाओं में, जो मात्रात्मक वित्तीय अर्थशास्त्र में अनुसंधान के आसपास घूम रहे हैं, हम गणित के बहुत से उपयोग करते हैं, और हम पहले से ही पोस्ट किए गए संयोजन का पालन करते हैं:

1. आपके द्वारा उपयोग किए जा रहे मुख्य स्रोत का लिंक प्रदान करें। हमारे लिए, ऐसा करने का सबसे आसान तरीका BibTex-हैंडल का उपयोग करना है, जो मूल रूप से एक पेपर के लिए एक आईडी है जिसमें शामिल सभी लोगों द्वारा देखा जा सकता है। विशिष्ट स्रोत के आधार पर, हम नियमित रूप से समीकरण संदर्भ भी जोड़ते हैं।

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

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

IMHO, सबसे महत्वपूर्ण अहसास यह है कि सूत्र अक्सर संदर्भ पर निर्भर करते हैं। प्रत्येक गणित पेपर जो मुझे पता है कि मॉडल के वातावरण को स्थापित करने में अपना समय लगता है; आपको भी ऐसा ही करना चाहिए।

Comments

संदर्भ को विस्तार से बताना एक महान विचार है, 'क्यों' से पहले 'क्यों' पर ध्यान केंद्रित करना वास्तव में सहायक हो सकता है।

— jrruc

Answer 4

पाठ में गणित की अभिव्यंजक शक्ति नहीं होती है

तुम सही हो। चूंकि आप पहले से ही इसे कोड के बाहर करने का एक तरीका ढूंढ रहे हैं, और टेक्स एक अधिगम वक्र के अलावा एक ओवरकिल है, मेरी सिफारिश इस प्रकार है:

OpenOffice.org/LibreOffice Math Equation Editor का उपयोग करें।

यह निःशुल्क है। यह खुला है।

आप इसे या तो नेत्रहीन उपयोग कर सकते हैं या आप एक विशेष भाषा में समीकरण लिख सकते हैं।

आपको तुरंत भाषा सीखना नहीं है क्योंकि जब आप GUI का उपयोग करते हैं, तो आपके लिए एक पैनल में "कोड" उत्पन्न होता है।

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

Comments

फिर क्या? टिप्पणियों के रूप में मूल संकेतन में गणित संकेतन के लिए सादा-पाठ कोड शामिल करें, या एक स्क्रीनशॉट लें और जावेदोक का उपयोग करें जैसे ओपी ने कहा कि वह TeX के साथ क्या कर सकता है?

— डोडेटस्टेस्ट्रोलर

@dodgethesteamroller हाँ, मेरा जवाब कहता है, "चूंकि आप पहले से ही इसे कोड के बाहर करने का तरीका ढूंढ रहे हैं, और टेक्स एक ओवरकिल है .."

— ट्यूलेंस कोरडोवा