हाइपरलिंक, बाह्य स्रोत कोड प्रलेखन [बंद]

Question

हम अभी भी स्रोत कोड के भीतर स्रोत कोड के प्राकृतिक भाषा विवरण (यानी, कारण कोड की एक पंक्ति क्यों लिखी गई थी) को एम्बेड करते हैं , बजाय एक अलग दस्तावेज़ के?

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

इस तरह के सॉफ्टवेयर डेवलपमेंट मैकेनिज्म में क्या खामियां होंगी?

प्रश्न को स्पष्ट करने में मदद करने के लिए एक मॉक-अप:

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

संभावित लाभ में शामिल हैं:

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

ध्यान दें:

• प्रलेखन विंडो ढह सकती है
• स्रोत फ़ाइलों को देखने या तुलना करने के लिए वर्कफ़्लो प्रभावित नहीं होगा
• कार्यान्वयन कैसे होता है यह एक विस्तार है; प्रलेखन हो सकता है:
  • स्रोत फ़ाइल के अंत में रखा गया;
  • सम्मेलन ( filename.c, filename.c.doc) द्वारा दो फ़ाइलों में विभाजित ; या
  • पूरी तरह से डेटाबेस संचालित
• हाइपरलिंक किए गए दस्तावेज़ीकरण से मेरा मतलब है कि बाहरी स्रोतों (जैसे स्टैकऑवरफ़्लो या विकिपीडिया) और आंतरिक दस्तावेज़ों को जोड़ना (यानी, उपडोमेन पर एक विकी जो व्यावसायिक आवश्यकताओं के दस्तावेज़ीकरण को पार कर सकता है) और अन्य स्रोत फाइलें (JavaDocs के समान)।

संबंधित धागा: उद्योग में प्रलेखन के लिए क्या है?

Comments

इस दृष्टिकोण में आप क्या फायदे देखते हैं?

— उऊ

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

— स्पेसट्रेकर

यह कैसे अलग है जो ग्रहण आपको पहले से देता है? i.stack.imgur.com/HEQ8w.jpg (कोड, पेजेज की रूपरेखा, और निचला पैनल javadoc जो कर्सर पर है)

"मेनू को बढ़ाना" टिप्पणी कोड के साथ इंटरव्यू है। यह बात अलग है।

— डेव जार्विस

इसके अलावा, Gson के लिए प्रलेखन Gson API का वर्णन करता है, जो बहुत अच्छा है, लेकिन यह जवाब नहीं देता है किGson() वस्तु को MainActivity वर्ग के संबंध में त्वरित क्यों किया जा रहा है, न ही यह किसी विशेष व्यावसायिक आवश्यकता को हल करने से संबंधित है। अपने द्वारा उपयोग किए जाने वाले API के बजाय, कोड का वर्णन करना, स्वतंत्र रूप से तृतीय-पक्ष JavaDocs से एक अलग विंडो में हो सकता है।

— डेव जार्विस

Answer 1

यह समस्या मुझे हर समय परेशान करती है, और मुझे सिर्फ इस बात पर एक विचार मिला कि हमें उस दिशा में प्रयास करना चाहिए और इसे हल करना चाहिए (अर्थात मुझे यह प्रश्न कैसे मिला)।

मुझे लगता है कि जब हमने स्रोत कोड में उपयोगकर्ता दस्तावेज़ीकरण को शामिल करने का निर्णय लिया था, तो लिंक किए गए प्रलेखन समस्या को गलत माना गया था। जैसे डोकोमो करता है।

सबसे पहले, उपयोगकर्ता प्रलेखन से कोड टिप्पणियों को अलग करने देता है।

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

उपयोगकर्ता टिप्पणी आपके पुस्तकालय / एपीआई का उपयोग करने की कोशिश कर रहे लोगों के लिए है, और उपयोग के उदाहरणों में शामिल हो सकते हैं, यह स्पष्टीकरण क्यों इसे लागू किया गया था, या कैसे पुस्तकालय का विस्तार किया जाए, इस पर निर्देश शामिल हैं। इस तरह की टिप्पणियाँ वास्तव में क्रियात्मक होती हैं।

मैं इस तथ्य पर सहमत हूं कि प्रलेखन को सादे पाठ में लिखा जाना चाहिए ताकि विक्रेता तय न हो और एक वीसीएस में जोड़ना आसान हो। लेकिन मुझे लगता है कि स्रोत फ़ाइल में उपयोगकर्ता दस्तावेज रखना कम से कम दो कारणों से एक बड़ी गलती थी:

• कोड पढ़ने के लिए कठिन
• लचीला पर्याप्त दस्तावेज नहीं है (मान लें कि मुझे एक ही उदाहरण कोड का उपयोग करके दो प्रलेखन पृष्ठों की आवश्यकता है या दो अलग-अलग स्रोत फ़ाइलों से कोड को इंटरलेवे करने के लिए एक प्रलेखन पृष्ठ की आवश्यकता है)।

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

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

क्या होगा अगर 2 तरह से बाध्यकारी होने के बजाय, हमारे पास एक ही रास्ता है? कोड की ओर इशारा करते हुए दस्तावेज। हमारे पास विशेष कमांड जैसे मार्कडाउन कोड हो सकते हैं:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

इससे कुछ परिवर्धन के साथ मार्कअप होने का लाभ होता है, और उचित साधनों के साथ, हम इसमें अधिक मूल्य जोड़ सकते हैं।

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

Answer 2

404 पृष्ठ नहीं मिला

कोड के साथ काम करते समय आप नहीं चाहते हैं कि आप टिप्पणी खो दें और जब आप कोड को अलग करेंगे और अलग दस्तावेजों में टिप्पणी करेंगे तो क्या होगा।

इसके अलावा, अपने कमेंट डॉक्यूमेंट और कोड डॉक्यूमेंट के बीच वर्जन रखने से अधिक दर्द होगा।

आपके द्वारा सुझाए गए कुछ सुझाव मुझे वास्तव में पसंद आए लेकिन 1 फ़ाइल में कोड और टिप्पणियां करते हुए भी आसानी से लागू किए जा सकते हैं।

Answer 3

संभावित नुकसान जो मुझे दिखाई देते हैं:

• आपको एक विशेष संपादक की आवश्यकता है जो इस सुविधा को लागू करता है

• कोड अब केवल सादा पाठ नहीं है, VCS-es में हेरफेर और प्रतिबद्ध करने के लिए आसान है

• कोड के साथ काम करने के लिए आपको दो बार अधिक स्क्रीन चौड़ाई की आवश्यकता है

अपने तर्कों के लिए:

एक बार में स्क्रीन पर अधिक स्रोत कोड और अधिक प्रलेखन

लेकिन अगर आप दो फाइलों को अगल-बगल देखना चाहते हैं तो आप असुविधाजनक हो सकते हैं।

स्रोत कोड की स्वतंत्र रूप से प्रलेखन संपादित करने की क्षमता (भाषा की परवाह किए बिना?)

मैं तर्क दूंगा कि यह वास्तव में नुकसान है। मैं व्यक्तिगत रूप से कोड के लिए प्रलेखन को यथासंभव बंद रखने की कोशिश करता हूं, ताकि यह पुराना न हो जाए।

मर्ज संघर्ष के बिना समानांतर में प्रलेखन और स्रोत कोड लिखें

फिर, संभवतः एक नुकसान। यदि आपके डॉक्स का कोड के साथ गहरा दखल है, तो आप उन्हें स्वतंत्र रूप से कैसे संपादित कर सकते हैं?

बेहतर पाठ स्वरूपण के साथ वास्तविक समय हाइपरलिंकड प्रलेखन

यदि यह कोड में है, तो यह पहले से ही वास्तविक समय है;) हाइपरलिंक के लिए, परिभाषा में कूदना पहले से ही अधिकांश आईडी में लागू है।

विभिन्न प्राकृतिक भाषाओं में अर्ध-वास्तविक समय मशीन अनुवाद

मैं यह नहीं देखता कि आप नियमित टिप्पणियों / दस्तावेज़ों के साथ ऐसा क्यों नहीं कर सकते।

कोड की प्रत्येक पंक्ति को स्पष्ट रूप से किसी कार्य, व्यावसायिक आवश्यकता आदि से जोड़ा जा सकता है।

मैं इस बारे में अनिश्चित हूं ... क्या इसे नियमित टिप्पणियों से हासिल नहीं किया जा सकता है?

जब कोड की प्रत्येक पंक्ति (मैट्रिक्स) लिखी गई थी, तो दस्तावेज़ स्वचालित रूप से टाइमस्टैम्प कर सकता है

क्या VCS-es इस तरह की जानकारी पहले से प्रदान नहीं करता है?

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

Comments

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

— डेव जार्विस

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

— फ़जर्री

Answer 4

सबसे पहले, डॉक्स टिप्पणियों को कोड के साथ जाने की जरूरत है - उन्हें कहीं और स्थानांतरित करने से केवल व्यावहारिक रूप से शून्य लाभ के लिए चीजों को संभालना अविश्वसनीय रूप से कठिन हो जाता है। तो परवाह क्यों!

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

आप वर्तमान में कोड टिप्पणियों में हाइपरलिंक एम्बेड कर सकते हैं, और आप Doxygen या Sphinx जैसे टूल का उपयोग करके कोड से दस्तावेज़ उत्पन्न कर सकते हैं। मुझे लगता है कि यह कुछ फैंसी एक्सटेंशन को ले जाएगा वह कोड संपादक को इन उपकरणों का बेहतर समर्थन करने के लिए।

मैं बग ट्रैकर या आवश्यकताओं टूल में कोड की किसी भी पंक्ति को लिंक नहीं करूंगा, यह आपके SCM के लिए बेहतर काम है। फिर आप प्रति प्रतिबद्ध कोड संपादन देख सकते हैं जो किसी कार्य से जुड़े हैं। मैं बग ट्रैकर के खिलाफ कोड में संग्रहीत प्रलेखन को एकीकृत नहीं करूंगा - यदि आप कभी भी किसी नए (hmm) में माइग्रेट करना चाहते हैं तो आप खराब हो जाएंगे, मैं इस सुविधा को अभी TFS में जोड़ा जा रहा है) या यदि आप देख सकते हैं अपना प्रतिबद्ध इतिहास खो दिया (जो होता है)

Answer 5

इसके अलावा जो @ बोगदान पहले से ही बताता है, मैं उसमें कुछ जोड़ूंगा:

• मैंने अपनी IDE को हमेशा एक साथ 2 फ़ाइलों के लिए कॉन्फ़िगर किया है। आपके द्वारा सुझाई जा रही सुविधा के साथ, मुझे समान जानकारी देखने के लिए मूल रूप से 2 मॉनिटरों की आवश्यकता होगी, और 3 वही करने की आवश्यकता है जो मैं अभी 2 के साथ कर रहा हूं।
• एक फ़ाइल के माध्यम से ब्राउज़ करते समय, आप तुरंत टिप्पणियां नहीं देखते हैं, और यदि आप नहीं जानते कि आप वास्तव में क्या देख रहे हैं, तो इसे ढूंढना बहुत मुश्किल है।
• एक फ़ाइल के माध्यम से खोज करते समय, मैं सीधे टिप्पणियों के माध्यम से (या आसानी से) खोज नहीं कर सकता।
• मुझे कभी-कभी विभिन्न परीक्षणों को करने की आवश्यकता होती है / ssh के माध्यम से, लाइव सर्वर पर कोड के छोटे टुकड़े लिखें । यद्यपि आप जो कार्यक्षमता कह रहे हैं, उसे VIM या अन्य कमांड लाइन संपादकों के साथ एकीकृत किया जा सकता है - सबसे अधिक संभावना है कि बहुत बड़ी समस्याएं होंगी

• अधिकांश IDE कोड / टिप्पणियों को ढहाने का समर्थन करते हैं , जिसके अंतिम परिणाम निम्नलिखित हैं:

  सामान्य के बजाय:

  

यदि आपको टिप्पणियों की आवश्यकता नहीं है, तो कोड को अधिक पठनीय बनाएं।

Answer 6

स्रोत कोड और प्रलेखन जिस तरह से किया जाना चाहिए।

http://jasmine.github.io/2.3/introduction.html