मेरी टीम में हमें एक महान स्रोत नियंत्रण प्रणाली मिली है और हमारे पास शानदार चश्मे हैं। जिस समस्या को मैं हल करना चाहता हूं वह यह है कि चश्मे को कोड के साथ अद्यतित कैसे रखा जाए। समय के साथ चश्मे उम्र बढ़ते हैं औरकोड और चश्मा सिंक में कैसे रखें? - क्या अच्छे उपकरण हैं
चश्मा बनाने वाले लोग स्रोत नियंत्रण को नापसंद करते हैं और प्रोग्रामर शेयरपॉइंट को नापसंद करते हैं।
मुझे यह सुनना अच्छा लगेगा कि दूसरों का क्या समाधान है? क्या कहीं कहीं खुश है?
मुझे लगता है कि गैर-शेयरपॉइंट विकी दस्तावेज़ीकरण को अद्यतित रखने के लिए अच्छा है। अधिकांश गैर-तकनीकी लोग समझ सकते हैं कि विकी का उपयोग कैसे करें, और अधिकांश प्रोग्रामर एक अच्छी विकी का उपयोग करने से खुश होंगे। शेयरपॉइंट में विकी और प्रलेखन नियंत्रण प्रणाली मेरी राय में, उपयोग करने के लिए घबराहट और निराशाजनक हैं।
Mediawiki एक अच्छा विकल्प है।
मुझे वास्तव में विकी पसंद है क्योंकि वे अब तक के सबसे कम दर्द को अपनाने और बनाए रखने के लिए हैं। वे आपको स्वचालित संस्करण नियंत्रण देते हैं, और आमतौर पर हर किसी के उपयोग के लिए बहुत सहज होते हैं। बहुत सी कंपनियां इसके लिए वर्ड, एक्सेल या अन्य प्रकार के दस्तावेज़ों का उपयोग करना चाहेंगे, लेकिन ऑनलाइन सब कुछ प्राप्त करना और एक सामान्य इंटरफेस से सुलभ होना महत्वपूर्ण है।
मैं जो वर्णन कर रहा हूं उसके लिए मुझे किसी विशेष रूप से अच्छे समाधान की जानकारी नहीं है; आम तौर पर, केवल एक ही समाधान जो मैंने देखा है कि वास्तव में इस तरह की चीजें सिंक में रखती हैं वे उपकरण हैं जो स्रोत कोड (डॉक्सिजन, जावाडोक) से दस्तावेज़ उत्पन्न करते हैं।
कोड के साथ सिंक्रनाइज़ेशन में रखने के लिए प्रयुक्त एक तकनीक literate programming है। यह कोड और दस्तावेज को एक ही फाइल में रखता है और प्रलेखन से संकलित कोड उत्पन्न करने के लिए प्रीप्रोसेसर का उपयोग करता है। जहां तक मुझे पता है कि यह तकनीक Donald Knuth उपयोगों में से एक है - और pay people पैसे से खुश है अगर उन्हें अपने कोड में बग मिलती है।
यह वास्तव में ठोस विनिर्देश तकनीक नहीं है। कोड और दस्तावेज तैयार करने के लिए बढ़िया है जो हमेशा मेल खाता है। एक विनिर्देश तैयार करने के लिए इतना अच्छा नहीं है जो किसी को प्रोग्राम लिखने में मदद करेगा। –
मैं इसे एक विकल्प के रूप में दे रहा हूं क्योंकि यह अलग है। लेकिन मुझे लगता है कि कोड में spec से जानकारी एम्बेडेड पर एक साक्षर कार्यक्रम बेहतर हो सकता है। यदि आप [tangle] [1] के लिए कोड देखते हैं, तो ऐसे अनुभाग हैं जो बहुत ही प्रतीत होते हैं - चरित्रों के प्रतिनिधित्व के तरीके के बारे में चर्चा में डिजाइन निर्णयों के कारण शामिल हैं। लेकिन मुझे लगता है कि अंतर वास्तव में जोर देने वाला है और अच्छे साक्षर प्रोग्रामिंग टूल की कमी इनलाइन टिप्पणियों को और अधिक उपयोगी बनाती है। [1]: http://tug.org/texlive/devsrc/Build/source/texk/web2c/tangle.web – garethm
नहीं। कोई खुश मध्य नहीं है। उनके पास अलग-अलग ऑडियंस और विभिन्न उद्देश्यों हैं।
यहां मैंने एक वास्तुकार और विशिष्ट लेखक के रूप में सीखा है: विनिर्देशों का दीर्घकालिक मूल्य है। इसे प्राप्त करें।
चश्मे, प्रोग्रामिंग शुरू करने के लिए अच्छा होने पर, समय के साथ अपना मूल्य खो देते हैं चाहे आप क्या करें। विनिर्देश के लिए दर्शक एक प्रोग्रामर है जिसकी अधिक अंतर्दृष्टि नहीं है। वे प्रोग्रामर गहराई से जानकार प्रोग्रामर में घुसपैठ करते हैं जिन्हें अब चश्मे की आवश्यकता नहीं होती है।
विनिर्देश के भाग - विशेष रूप से अवलोकन - कुछ दीर्घकालिक मूल्य हो सकते हैं।
यदि शेष स्पेक का मूल्य था, तो प्रोग्रामर उन्हें अद्यतित रखेंगे।
कोड में एम्बेडेड टिप्पणियों का उपयोग करना और उन टिप्पणियों को निकालने और वर्तमान लाइव दस्तावेज़ों का उत्पादन करने के लिए एक उपकरण का उपयोग करना अच्छा काम करता है। जावा इसे जावाडोक के साथ करता है। पायथन यह epydoc या Sphinx के साथ करता है। सी (और सी ++) Doxygen का उपयोग करें। बहुत सारे विकल्प हैं: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
अवलोकन को मूल चश्मे से बाहर निकाला जाना चाहिए और कोड में रखा जाना चाहिए।
एक अंतिम दस्तावेज़ निकाला जाना चाहिए। यह दस्तावेज़ स्पेक अवलोकन और कोड विवरण का उपयोग करके विनिर्देशों को प्रतिस्थापित कर सकता है।
जब प्रमुख ओवरहाल की आवश्यकता होती है, तो नए विनिर्देश होंगे। मौजूदा विनिर्देशों में संशोधन की आवश्यकता हो सकती है। कूद-बंद बिंदु ऑटो जनरेटेड विनिर्देश दस्तावेज़ है। कल्पना लेखक उन लोगों के साथ शुरू कर सकते हैं और अपने दिल की सामग्री में जोड़/बदल/हटा सकते हैं।
मैं सुझाव दूंगा कि चश्मे के पास दीर्घकालिक ऐतिहासिक मूल्य है; समझ में आया कि शुरुआती दिनों में कुछ डिज़ाइन विकल्पों को एक परियोजना में बाद के बिंदुओं पर बहुत उपयोगी क्यों बनाया जा सकता है; लेकिन मैं आपसे बहुत सहमत हूं। –
डिजाइन निर्णय महत्वपूर्ण हैं। वे एक सिंहावलोकन में हैं - विशेष रूप से एक वास्तुकला सिंहावलोकन - विस्तृत प्रोग्रामिंग चश्मा नहीं। –
जितना संभव हो सके spec को निष्पादन योग्य, आरएसपीईसी, या डॉक्टरेट और इसी तरह के ढांचे के माध्यम से निष्पादन योग्य होना चाहिए। कोड का नमूना यूनिट परीक्षण और कोड के साथ दस्तावेज किया जाना चाहिए जिसमें अच्छी तरह से विधियों और चर शामिल हैं।
तब स्पेक प्रलेखन (अधिमानतः विकी में) आपको चीजों का उच्च स्तर का अवलोकन देना चाहिए - और इससे अधिक परिवर्तन नहीं होगा या जल्दी से सिंक से बाहर नहीं निकल जाएगा।
इस तरह का एक दृष्टिकोण निश्चित रूप से spec और कोड को सिंक में रखेगा और जब वे सिंक हो जाएंगे तो परीक्षण विफल हो जाएंगे।
कहा जा रहा है कि उपरोक्त कई परियोजनाओं पर उपरोक्त पाई-इन-द-आकाश है। उस मामले में, एस लॉट सही है, इसे खत्म करो। वे सिंक में नहीं रहते हैं। स्पेक्ट्रम को देखें कि डेवलपर्स को रोडमैप दिया गया था, न कि उन्होंने जो किया उसके दस्तावेज।
यदि वर्तमान स्पेक होना बहुत महत्वपूर्ण है, तो के बाद कोड लिखने के लिए आवंटित परियोजना (या फिर लिखना) आवंटित परियोजना पर विशिष्ट समय होना चाहिए। फिर यह सटीक होगा (जब तक कोड में परिवर्तन नहीं होता)।
इनमें से सभी का विकल्प नमूना और कोड को स्रोत नियंत्रण में रखना है और यह जांचने के लिए चेक-इन की समीक्षा की गई है कि कोड के साथ spec बदल गया है। यह विकास प्रक्रिया को धीमा कर देगा, लेकिन यदि यह वास्तव में महत्वपूर्ण है ...
हाँ। कोड में कल्पना! – Sake
यह एक बड़ी समस्या है। यहां मुद्दा उठाने के लिए धन्यवाद, क्रिस। – DOK
मैं दूसरा डीओके करूंगा, साथ ही मैं शेयरपॉइंट को नापसंद करता हूं। +1 –