ओपन-सोर्स प्रोजेक्ट्स के लिए कोड ओवरव्यू क्यों नहीं हैं? [बन्द है]


60

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

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

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

लेकिन फिर भी मैंने इनमें से एक भी "कोड ओवरव्यू" नहीं देखा है। क्यों? क्या ऐसी चीजें हैं और मैं उन्हें याद कर रहा हूं? चीजें जो मैं जैसा वर्णन कर रहा हूं, वैसा ही काम करते हैं? या यह पूरी तरह से बेकार विचार है, जैसा कि हर कोई है, मेरे अलावा, कोड के हजारों लाइनों के साथ परियोजनाओं को आसानी से समझ सकता है?


7
आप एक डिजाइन दस्तावेज़ का मतलब है? मैंने प्रत्येक पैकेज के विवरण के साथ दुर्लभ परियोजना देखी है, लेकिन यह आमतौर पर पहले से ही एक एपीआई है।
शाफ़्ट ने

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

9
दस्तावेज़ीकरण वास्तविक व्यवहार के सापेक्ष पुराना या गलत हो सकता है। कोड नहीं कर सकते। इसलिए ज्यादातर प्रोजेक्ट्स कोड पसंद करते हैं।
पॉल ड्रेपर

5
इसके अलावा यह समझना आसान है कि आप किसी परियोजना के बारे में कितना सीख सकते हैं यदि आप 2 घंटे या उससे अधिक समय के लिए रसोई टाइमर सेट करते हैं और जस्ट रीड इट (टीएम)।
कोस

43
समुदाय-संचालित दुनिया में आपका स्वागत है: यदि ऐसा नहीं किया गया है, तो ऐसा इसलिए है क्योंकि आपने इसे नहीं किया है :)
mgarciaisaia

जवाबों:


60

क्योंकि इस तरह के दस्तावेज़ को बनाने और बनाए रखने के लिए यह अतिरिक्त प्रयास है, और बहुत से लोग संबंधित लाभों को नहीं समझते हैं।

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

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


6
खैर, ऐसा लगता है कि इसका उत्तर हां है: gnunet.org/gnunet-source-overview
fiatjaf

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

8
@keshlam - इसका मतलब है कि अगर आप पहले से ही परियोजना के लिए योगदानकर्ता हैं ... लेकिन अगर आप एक संभावित योगदानकर्ता हैं जो यह जानने का प्रयास कर रहे हैं कि कोड कैसे काम करता है, तो आप सबसे खराब व्यक्ति हैं जो लिखना संभव है वह दस्तावेज़ ....
जॉन स्टोरी

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

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

14

सूखा, कठोर सत्य?

दस्तावेज़ीकरण नहीं किया जाता है क्योंकि परियोजनाएं इसके बिना कर सकती हैं।

यहां तक ​​कि ओपन सोर्स प्रोजेक्ट्स में अक्सर कड़ी प्रतिस्पर्धा होती है। इस तरह की अधिकांश परियोजनाएं बड़े कंधों से शुरू नहीं होती हैं, वे एक उज्ज्वल विचार शुरू करते हैं, अक्सर एक आदमी उज्ज्वल विचार।

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

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

फिर भी, परियोजना प्रबंधक प्रलेखन नहीं बनाने का विकल्प चुन सकता है।

एक गतिशील, बढ़ती परियोजना दोनों धीमा हो जाएगा और प्रलेखन वास्तव में कोड के पीछे पिछड़ जाएगा, जबकि अनुवाद, विकल्प, प्रबंधकों को प्लग लागू करने के लिए यह वास्तव में कठिन बढ़ाया जा रहा है ...

आमतौर पर क्या होता है:

  1. एक संक्षिप्त परिचयात्मक दस्तावेज़ बनाया गया है, इस बारे में कि परियोजना क्या है और यह कहाँ जा रही है (प्रसिद्ध "रोडमैप")।
  2. यदि संभव हो तो, एक एपीआई विकसित किया जाता है और उस अंतर्निहित कोड के थोक पर "प्रलेखित कोड" के रूप में चुना जाता है।
  3. निःसंदेह एपीआई लेकिन अन्य कोड भी रिफॉर्मेटेड हैं और "PHPdoc" / "Javadoc" आदि में विशेष टिप्पणियां जोड़ी जाती हैं। वे बिताए समय और इनाम के बीच एक सभ्य समझौता करते हैं: यहां तक ​​कि एक मामूली प्रोग्रामर आमतौर पर जानता है कि कैसे एक लाइनर को अपने कार्यों का वर्णन करना लिखना है, मापदंडों को "ऑटो" के रूप में अच्छी तरह से प्रलेखित किया जाता है और पूरे अपने संबंधित कोड से बंधा होता है और इस तरह वे प्रलेखन से बचते हैं। desyncing "और पिछड़ रहा है विकास।
  4. ज्यादातर, एक मंच बनाया जाता है। यह एक शक्तिशाली सोशल मीडिया है जहाँ अंत उपयोगकर्ता और प्रोग्रामर एक-दूसरे से बात कर सकते हैं (और अपने साथियों के बीच, संभवतः "केवल देवता" उपसमूह में)। यह बहुत से ज्ञान को धीरे-धीरे उभरने और समुदाय द्वारा बनाए गए समेकित करने की अनुमति देता है (पढ़ें: डेवलपर्स टीम पर वजन नहीं) FAQs और HOWTO।
  5. वास्तव में बड़ी परियोजनाओं में, एक विकी का उत्पादन भी किया जाता है। मैं "बड़ी परियोजनाएं" बताता हूं क्योंकि वे अक्सर विकी बनाने के लिए पर्याप्त अनुयायियों वाले होते हैं (एक देव करता है) और फिर वास्तव में इसे "नंगे हड्डियों" (समुदाय करता है) से परे भरते हैं।

2
वाह!! हम दो (और काम) पूरी तरह से अलग दुनिया में रहते हैं। वर्तमान में आप जहां भी काम कर रहे हैं, वहां से तेजी से बाहर निकलें और एक कंपनी ढूंढें (ऐसे कई हैं) जहां यह सही ढंग से हो जाता है क्योंकि यह वास्तव में आपको पैसे बचाता है। कभी भी नुकीले सिर वाले मैनेजरों / काउबॉय कोडर्स को अन्यथा बताने की कोशिश न करें।
मग

6
+1, मैं आपके लगभग सभी बिंदुओं से सहमत हूं, एकमात्र कथन जो मैं दृढ़ता से अस्वीकार करता हूं, वह यह है कि मापदंडों को "ऑटो" दस्तावेज मिलता है । जब हम केवल वाक्य रचना / प्रकार की बाधाओं के बजाय स्पष्टीकरण के बारे में सोचते हैं, तो कुछ भी "ऑटो-डॉक्यूमेंटेड" नहीं होता है; शैली में एक उत्पन्न टिप्पणी एक एक्सएक्सएक्स विधि के लिए एक्स लौटाता है सहायक दस्तावेज नहीं है, यह बिना किसी अतिरिक्त जानकारी के सिर्फ एक भराव है।
या मैपर

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

क्या यह संभव नहीं है कि वे परियोजनाएं विफल हो जाएं क्योंकि वे दस्तावेज नहीं करते हैं? और दस्तावेज़ द्वारा, मेरा मतलब है कि योजना, ताकि आप समझ सकें, बजाय कीबोर्ड पर बैठकर और पाउंड के दूर। यहाँ एक परियोजना जीवन-चक्र के लिए मेरा अनुमान है, सभी आंकड़े +/- 5%। सामने का सामान (आवश्यकताएं और उपयोग के मामले, वास्तुकला, विस्तृत डिजाइन) 50%, कोडिंग 10 से 15%, परीक्षण, बाकी। "अगर आप योजना बनाने में विफल रहते हैं, तो आप असफल होने की योजना बनाते हैं"
मग

6

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

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

कोड की एक पंक्ति को बदलने के लिए आपको आसपास के कोड की सीमित समझ की आवश्यकता होती है। ऐसा करने के लिए आपको कभी भी पूरे कोड आधार को नहीं समझना चाहिए। यदि आपके पास उस प्रकार के फ़ंक्शन का एक उचित विचार है जो टूट गया है, तो अक्सर निर्देशिका पदानुक्रम को जल्दी से नेविगेट करना संभव है।

कोड की एक पंक्ति को बदलने के लिए आपको उस विधि को समझना होगा जिसके भीतर रेखा पाई जाती है। यदि आप समझते हैं कि विधि का अपेक्षित व्यवहार क्या है, तो आपको कार्यक्षमता में सुधारात्मक परिवर्तन या विस्तार करने में सक्षम होना चाहिए।

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

मेरा लेख देखें कि इस तरह के बदलाव कैसे किए जा सकते हैं, उदाहरण के लिए टिनिअ में SHA-2 जोड़ना । मुझे इंटरफ़ेस उत्पन्न करने के लिए उपयोग किए जाने वाले कोड की बेहद सीमित समझ है।


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

+1 ओपन सोर्स के बारे में कुछ खास नहीं है। उद्योग में काम करने के मेरे 10 वर्षों के अनुभव में मैंने एक बार भी अवलोकन दस्तावेज नहीं देखा है। आम तौर पर ऐसा होता है कि नियोक्ता आपके रोजगार के पहले महीने में शून्य उत्पादकता की उम्मीद करते हैं क्योंकि आप कोडबेस का अध्ययन कर रहे हैं। "ओवरव्यू" आमतौर पर आपके सहकर्मियों के प्रश्न पूछने के रूप में कार्यान्वित किया जाता है
स्लीबेटमैन

5

क्या ऐसी चीजें हैं और मैं उन्हें याद कर रहा हूं? चीजें जो मैं जैसा वर्णन कर रहा हूं, वैसा ही काम करते हैं?

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


यह एक टिप्पणी की तरह अधिक पढ़ता है, देखें कि कैसे जवाब दें
gnat

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

1
मुझे लगता है कि पूछे गए प्रश्न का उत्तर अभाव है, "ओपन-सोर्स प्रोजेक्ट्स के लिए कोड ओवरव्यू क्यों नहीं हैं?"
gnat

3
मैं इसे के रूप में लिखा जब, वास्तव में, वहाँ सवाल का सही ढंग से प्रतिक्रिया करने के लिए संभव नहीं है तर्क है कर रहे हैं कुछ खुला स्रोत परियोजनाओं के लिए कोड overviews। मैंने अपने उत्तर को यह स्पष्ट करने के लिए संपादित किया है कि मैं उपयोगकर्ता के छूटे हुए उदाहरणों के अनुरोध का उत्तर दे रहा हूं।
bjmc

1
जैसा प्रश्न लिखा गया है, "क्या ऐसी चीजें हैं और मैं उन्हें याद कर रहा हूं?" यह उत्तर निश्चित रूप से प्रतिक्रिया करता है, ऐसे कोड साक्षात्कारों के मौजूदा संग्रह की ओर इशारा करता है। जैसा कि मुझे लगता है कि यह सवाल का एक शानदार (और उपयुक्त) उत्तर है।
जिम गैरिसन

4

क्योंकि ओपन-सोर्स तकनीकी लेखकों की तुलना में कहीं अधिक ओपन-सोर्स प्रोग्रामर हैं।

दस्तावेज़ीकरण में रखरखाव और तारीख तक का समय लगता है। दस्तावेज़ जितना अधिक भारी होगा, उतना ही अधिक होगा। और कोड के साथ तालमेल नहीं होने वाला प्रलेखन बेकार से भी बदतर है: यह खुलासा करने के बजाय गुमराह करता है और छुपाता है।

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

शिपिंग कोड जीतता है। शिपिंग कोड के अलावा अन्य चीज़ों में लगाए गए प्रयासों की मात्रा को कम करने से कोड शिप को अधिक बार बनाया जा सकता है, और संसाधनों से बाहर चलने से पहले जहाज होने की अधिक संभावना है।

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

हालांकि, सफलता की तरह कुछ भी नहीं बेचता है: एक परियोजना जो काम नहीं कर रही है या कुछ भी दिलचस्प नहीं है, शायद ही कभी डेवलपर्स को आकर्षित करती है।

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

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

अंत में, वर्तमान डेवलपर्स के ऊपर उल्लिखित कारणों से कोड आधार पर विशेषज्ञ होने की संभावना है। इस तरह के प्रलेखन को लिखने से उन्हें कोड आधार को समझने में मदद नहीं मिलती है , क्योंकि उनके पास पहले से ही ज्ञान है, यह केवल अन्य डेवलपर्स की मदद करता है। बहुत से ओपन सोर्स डेवलपमेंट "स्कैचिंग इट इट" से आधारित है, जो डेवलपर के पास कोड के साथ होता है: प्रलेखन की कमी जो पहले से ही कहती है कि डेवलपर को शायद ही कभी पता है।


+1 "प्रलेखन आसानी से पहली जगह में कोड लिखने के रूप में लंबे समय तक ले जा सकता है" - या अधिक समय तक!
मार्को

-1

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

बस एक काफी लोकप्रिय नाम: ब्लूज़। सौभाग्य एक अच्छा ट्यूटोरियल खोजने, अन्य तो पास के उपकरणों के लिए स्कैन करने के लिए।


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

@ORMapper की शुरुआत "Bluez - सबसे बड़ी लिनक्स रहस्य" से होती है । लिनक्स के लिए केवल ब्लूटूथ लाइब्रेरी के रूप में, मुझे यह विश्वास करना कठिन लगता है कि यह दस्तावेज़ीकरण नहीं है क्योंकि यह एक अतिरिक्त प्रयास है। नर्क है, डॉक्सीजेन है, और सरल ट्यूटोरियल लिखना कितना कठिन है?
B:06овиЈ 12

@ORMapper फिर लिनक्स कर्नेल है। यदि आप कुछ याद कर रहे हैं (एक कर्नेल चालक की तरह), यदि आपकी कंपनी विशेषज्ञता याद कर रही है, तो आप या तो किसी को किराए पर ले सकते हैं, या एक फ्रीलांसर या एक कंपनी ढूंढ सकते हैं जो आपके लिए ऐसा करेगी। तो, यह खुला स्रोत है, लेकिन यह एक मूल्य के साथ आ रहा है
B'ови

@ORMapper तब ओपन सोर्स प्रोजेक्ट होते हैं, जिसमें पेपर प्रारूप में प्रलेखन होता है। इसलिए आप एक पुस्तक खरीदते हैं, और कोई अन्य दस्तावेज नहीं दिया जाता है। क्या यह दस्तावेज अपंग है या नहीं?
भाग

2
इसके लायक क्या है, मैंने देखा है कि कम से कम आश्चर्य की बात है कि क्या यह जानबूझकर किया गया है। जब एक ही समूह आधे-अधूरे दस्तावेज डाल रहा है, तो आपको एक पुस्तक या एक प्रशिक्षण वर्ग बेचने के लिए खुश होने की तुलना में अधिक है, यह उस निष्कर्ष तक पहुंचने के लिए बहुत अधिक निंदक नहीं लेता है।
cHao
हमारी साइट का प्रयोग करके, आप स्वीकार करते हैं कि आपने हमारी Cookie Policy और निजता नीति को पढ़ और समझा लिया है।
Licensed under cc by-sa 3.0 with attribution required.