जावा प्रोग्राम की उच्च-स्तरीय संरचना का दस्तावेजीकरण कैसे करें?

Question

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

• प्रत्येक वर्ग और विधि के लिए Javadocs
• कोड का उपयोग कैसे करें
• कोड की उच्च-स्तरीय संरचना का वर्णन करना

मेरा उच्च-स्तरीय प्रश्न है: क्या आप उन शब्दों और आरेखों का एक अच्छा उदाहरण प्रदान कर सकते हैं जिनका उपयोग किसी कार्यक्रम की उच्च-स्तरीय संरचना का वर्णन करने के लिए किया जा सकता है? इसमें उप-प्रश्न शामिल हैं:

1. हम कैसे दिखाते हैं कि कौन से वर्ग किस पैकेज में निहित हैं?
2. हम कैसे दिखाते हैं कि अन्य पैकेजों पर क्या पैकेज निर्भर करता है?
3. हम कैसे दिखाते हैं कि प्रोग्राम में ऑब्जेक्ट्स / क्लासेस एक साथ कैसे काम करते हैं?
4. हमने अपने कोड के डिज़ाइन में डोमेन-संचालित डिज़ाइन सिद्धांतों का उपयोग करने की कोशिश की है । हम डोमेन में वस्तुओं के बीच पत्राचार और इन वस्तुओं को एन्कोडिंग करने वाले विशेष स्रोत कोड फ़ाइलों को कैसे दिखाते हैं? (मेरी "सर्वव्यापी भाषा" नीचे दिए गए प्रोजेक्ट का विवरण देखें।)

मैंने अब तक क्या किया है

सर्वव्यापी भाषा

हमने एक फाइल में कोड का "सर्वव्यापी भाषा" विवरण ubiquitous-language.mdनीचे दिया है।

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

प्रत्येक अवधि में, निम्नलिखित घटनाएँ होती हैं:

1. यदि एक शिपमेंट को वर्तमान अवधि में सुविधा पर पहुंचने के लिए निर्धारित किया जाता है , तो सुविधा का इन्वेंट्री स्तर एक्स इकाइयों द्वारा बढ़ाया जाता है।
2. यदि शेड्यूल इंगित करता है कि वर्तमान अवधि रिपोर्टिंग अवधि है, तो सुविधा आपूर्तिकर्ता को एक रिपोर्ट सबमिट करती है । आपूर्तिकर्ता प्राप्त हो सकता है रिपोर्ट तत्क्षण या, के रूप में द्वारा निर्दिष्ट, कई हफ्तों तक का विलंब अनुसूची ।
3. यदि आपूर्तिकर्ता को एक रिपोर्ट प्राप्त हुई है , तो पुनरावृत्ति नीति के आधार पर , यह एक्स इकाइयों की पुनःपूर्ति मात्रा की गणना करेगा। उत्पाद की एक्स इकाइयों की एक शिपमेंट एल अवधि के एक प्रमुख समय के बाद आने वाली है।
4. ग्राहक सुविधा पर पहुंचते हैं और उत्पाद की एक्स इकाइयों की मांग करते हैं। किसी भी unmet की मांग खो जाती है।

स्रोत कोड संरचना

हम एक फ़ाइल में कोड का अधूरा "उच्च-स्तरीय" विवरण structure.md, नीचे सामग्री डालते हैं।

पैकेज स्तर की संरचना

उच्चतम स्तर पर, स्रोत कोड को तीन पैकेजों में व्यवस्थित किया जाता है

• com.gly.sfsmainविधि के साथ मुख्य वर्ग इस पैकेज में रहता है।
• com.gly.sfs.model डोमेन मॉडल कक्षाएं इस पैकेज में रहती हैं।
• com.gly.sfs.util इस पैकेज में हेल्पर कक्षाएं रहती हैं।

Comments

meta.programmers.stackexchange.com/questions/6483/…

— gnat

जब आप "कोड की उच्च-स्तरीय संरचना" कहते हैं, तो क्या आपका मतलब है कि कौन से वर्ग किस पैकेज में हैं? आप ऐसा कर सकते हैं कि अपने वर्ग आरेख में कक्षाओं के आसपास एक बिंदीदार रेखा खींचकर जो एक विशिष्ट पैकेज से संबंधित हो, और पैकेज नाम के साथ बिंदीदार रेखा को लेबल करें। वर्ग आरेखों के उदाहरणों को खोजना काफी आसान है ।

— रॉबर्ट हार्वे

शैक्षणिक कोड जारी करने के लिए बड़ा सहारा।

— फेलिक्स

@RobertHarvey प्रश्न के लिए मेरे संपादन देखें। यह दिखाना कि कौन से वर्ग हैं जिनमें संकुल अधिक सीधा है, यह दर्शाता है कि कक्षाएं एक साथ कैसे काम करती हैं और अधिक मुश्किल है।

— आई लाइक कोड कोड

आप पैकेज स्तर के javadoc को भी जोड़ना चाह सकते हैं।

— हेलेम

Answer 1

आम तौर पर , आप जिस उद्देश्य का वर्णन करते हैं, उसके लिए आप यूएमएल का उपयोग करेंगे। यूएमएल मूल रूप से दो प्रकार के आरेखों में टूट जाता है: संरचनात्मक और व्यवहारिक।

संरचनात्मक आरेखों में शामिल हैं: रचना, परिनियोजन, पैकेज, वर्ग, वस्तु और घटक। व्यवहार आरेखों में शामिल हैं: अनुक्रम, राज्य मशीन, संचार, उपयोग मामला, गतिविधि और इंटरैक्शन अवलोकन।

आप जो बताने की कोशिश कर रहे हैं, उसके आधार पर, आप इनमें से कुछ आरेखों को चुनते हैं जो सबसे अच्छा प्रतिनिधित्व करते हैं जो आप व्यक्त करने की कोशिश कर रहे हैं, और ऐसा करके आप वार्तालाप को "एक स्तर ऊपर ले जाने" की अनुमति देते हैं। तरीकों, मापदंडों और कोड के बारे में बात करने के बजाय, आप बातचीत के अनुक्रम, या स्थिर वर्ग पर निर्भरता, या जो भी आरेख बनाने के लिए चुनते हैं, के बारे में बात कर रहे हैं।

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

http://omarfrancisco.com/wp-content/uploads/2011/07/sequencediagram.png

मैंने अपने जीवन में इस चित्र को पहले कभी नहीं देखा है, लेकिन मैं इस प्रणाली के बारे में कई बातें बता सकता हूं। चार प्रमुख घटक हैं (आपके सिस्टम में संज्ञाएं - आमतौर पर कक्षाएं): देखें, नियंत्रक, डेटा प्रॉक्सी, और डेटा प्रदाता। तीर "व्यवहार" या विधि इनवोकेशन हैं। एक अनुक्रम आरेख मूल रूप से घटकों के एक समूह के बीच एक एकल महत्वपूर्ण बातचीत को दिखाने के लिए अच्छा है। आपके पास अपने सिस्टम के माध्यम से प्रत्येक महत्वपूर्ण प्रवाह के लिए एक अनुक्रम आरेख है। मैं इस विशेष आरेख से बता सकता हूं कि "नियंत्रक" "phoneIsComplete ()" नामक एक विधि को उजागर करता है, जो बदले में DataProviderProxy के "लुकअपफोन ()" विधि पर निर्भर करता है, जो बदले में DataPider के "लुकअपफोन ()" विधि पर निर्भर करता है।

अब, आप कराह सकते हैं और सोच सकते हैं "बदसूरत ... यह मुझे सिस्टम की एक बड़ी तस्वीर नहीं देता है - यह सिस्टम के माध्यम से व्यक्तिगत बातचीत है"। सिस्टम के परिष्कार के आधार पर, यह एक वैध चिंता का विषय हो सकता है (सरल सिस्टम निश्चित रूप से अनुक्रम डायग्राम के एक संग्रह के साथ ही प्राप्त कर सकता है)। इसलिए, हम संरचनात्मक आरेखों की ओर बढ़ते हैं और हम एक स्थिर वर्ग आरेख की तरह देखते हैं:

http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg

क्लास डायग्राम हमें दो महत्वपूर्ण चीजों का पता लगाने में मदद करते हैं: कार्डिनैलिटी, और क्लास रिलेशनशिप प्रकार। कक्षाएं अलग-अलग तरीकों से एक दूसरे से संबंधित हो सकती हैं: संघ, एकत्रीकरण और रचना। तकनीकी रूप से, "स्थिर वर्ग संबंधों" और "उदाहरण रिश्तों" के बीच अंतर है। हालाँकि, व्यवहार में आप इन रेखाओं को धुंधला देखते हैं। मुख्य अंतर यह है कि स्थिर वर्ग संबंधों में आमतौर पर कार्डिनैलिटी शामिल नहीं होती है। आइए ऊपर दिए गए उदाहरण को देखें और देखें कि हम क्या देख सकते हैं। सबसे पहले, हम देख सकते हैं कि "विशेष आदेश" और "सामान्य आदेश" "आदेश" (विरासत) के उपप्रकार हैं। हम यह भी देख सकते हैं कि एक ग्राहक के पास एन ऑर्डर (जो "सामान्य आदेश", "आदेश", या "विशेष आदेश") हो सकते हैं - ग्राहक वस्तु नहीं है ' वास्तव में नहीं पता हम कई विधियों (प्रत्येक वर्ग बॉक्स के निचले आधे भाग में) और गुण (प्रत्येक वर्ग बॉक्स के शीर्ष आधे) को भी देख सकते हैं।

मैं लंबे समय तक यूएमएल आरेखों के बारे में बात कर सकता था, लेकिन यह मूल बातें है। उम्मीद है कि मदद करता है।

TLDR; एक व्यवहारिक और एक संरचनात्मक यूएमएल आरेख चुनें, इसे बनाने का तरीका जानें, और आप जो हासिल करना चाहते हैं उसे पूरा करेंगे।

Answer 2

यदि आपको उन चीजों का वर्णन करने में कठिनाई हो रही है जैसे कि आपके कार्यक्रम की उच्च-स्तरीय संरचना कैसे काम करती है, और कक्षाएं एक साथ कैसे काम करती हैं, तो निम्नलिखित बातों पर विचार करें:

A picture is worth a thousand words.

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

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

Comments

+1, आम कार्यों के कोड उदाहरण पहली चीज है जिसे कोई भी सीखने की कोशिश कर रहा है जो एपीआई सीखना चाहता है। Javadocs और वर्गों के बीच संबंध के कुछ विवरण रिक्त स्थान को भर देंगे, लेकिन पर्याप्त नहीं हैं।

— डोभाल

UML का उल्लेख नहीं करने के लिए +1 ।

— डॉक्टर ब्राउन

@DocBrown UML निश्चित रूप से हर काम का साधन नहीं है। हालाँकि , यदि आप कुछ ऐसा बना रहे हैं जो यूएमएल आरेखों में से एक के पैटर्न को फिट करता है (उदाहरण के लिए, वर्ग संबंधों को मॉडलिंग करता है ), तो यूएमएल एक प्रारूप प्रस्तुत करता है जिससे पाठक परिचित होने की संभावना रखते हैं, और परिचितता पठनीयता को आसान बनाती है।

— कैट

@DocBrown यूएमएल इस मामले में एक बुरा समाधान क्यों होगा?

— ओन्नो

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

— डॉक्टर ब्राउन

Answer 3

UML, जबकि अक्सर इसे बनाने से पहले सॉफ्टवेयर का उपयोग किया जाता था, उपयोगी हो सकता है। कई अलग-अलग आरेख हैं जो उपयोग-मामलों, वर्ग-इंटरैक्शन आदि का वर्णन करते हैं। आप यहां इसके बारे में अधिक देख सकते हैं ।

Answer 4

मुझे एक एप्लिकेशन के भीतर घटकों के बीच या किसी वितरित एप्लिकेशन में सेवाओं के बीच बातचीत का वर्णन करने के लिए https://www.webfterencediagrams.com/ बेहद उपयोगी उपकरण लगता है । यह यूएमएल अनुक्रम आरेख को बनाने और बनाए रखने की प्रक्रिया को बहुत आसान बनाता है।

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

इसके अतिरिक्त, छवि प्राप्त करने के लिए कुछ डाउनलोड विकल्प हैं। विकी में आरेख को एम्बेड करने के कुछ आसान तरीके भी हैं। तो यह एक प्रणाली में घटकों या सेवाओं के बीच की बातचीत का वर्णन करने के लिए एक महान संचार उपकरण है, साथ ही साथ टीम के साथ संवाद करना भी है।