कोड प्रलेखन उत्पादकता लाभ / हानि पर अध्ययन

Question

बहुत खोज के बाद, मैं सॉफ्टवेयर विकास की दुनिया में ज्ञात एक मूल प्रश्न से संबंधित उत्तर देने में असफल रहा:

क्या पता है:

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

परंतु:

पूरी तरह से प्रलेखन (या यहां तक ​​कि एक एपीआई) होने के बाद यह नए और अनुभवी डेवलपर्स में उत्पादकता लाभ (एक मान लेता है) जब वे सुविधाओं को जोड़ रहे हैं, या सड़क के नीचे कीड़े को ठीक कर रहे हैं।

प्रश्न:

क्या इस तरह के प्रलेखन की गारंटी उत्पादकता में डाउन-इन-रोड (एक सख्त आर्थिक अर्थ में) से हासिल करने के लिए अतिरिक्त विकास समय की आवश्यकता है?

मैं केस स्टडी की तलाश कर रहा हूं, या उत्तर जो निष्कर्ष निकाले गए हैं उनका समर्थन करते हुए उनके साथ वस्तुनिष्ठ प्रमाण ला सकते हैं।

अग्रिम में धन्यवाद!

Comments

यदि आप राय खोज रहे हैं, तो यह प्रोग्रामर पर आधारित है।

— डेविड थॉर्नले

मैं असहमत हूं कि इसे स्थानांतरित किया जाना चाहिए था। स्पष्ट करने के लिए, मैं दृढ़ता से किसी भी अध्ययन की तलाश कर रहा हूं जो किया गया है।

— JT

संपादित। क्या कोई मॉडरेटर कृपया इसे स्टैक ओवरफ्लो में वापस भेज सकता है, जहां इस सवाल का व्यापक दर्शकों को आनंद मिलेगा, जिससे इसकी संभावना बढ़ जाएगी।

— JT

मुझे नहीं लगता कि यह एसओ के लिए एक उपयुक्त प्रश्न है क्योंकि यह कोडिंग प्रश्न नहीं है, लेकिन कोडिंग के बारे में एक प्रश्न है। मुझे वास्तव में लगता है कि यह प्रोग्रामर्स के लिए एक सही सवाल है। '

— ChrisF

Answer 1

लेख "टाइपोग्राफिक शैली कॉस्मेटिक से अधिक है" बल्कि पुरानी है लेकिन यह बहुत दिलचस्प है: http://portal.acm.org/citation.cfm?id=78611 ।

पुराना होने के नाते, इसमें उन सभी फैंसी सामान शामिल नहीं हैं जो इन दिनों संभव होंगे लेकिन यह स्पष्ट रूप से दिखाता है कि कोड प्रलेखन मायने रखता है।

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

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

समूह को संतुलित करने के लिए उनके पास समान संख्या में विशेषज्ञ और जूनियर प्रोग्रामर थे।

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

लेख अधिक कहता है, लेकिन यह वह है जिसे मैं स्मृति से याद कर सकता हूं (मुझे अभी भी कहीं मुद्रित लेख होना चाहिए)।

Answer 2

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

मैं अच्छी तरह से, सामान्य ज्ञान को छोड़कर, किसी भी कठिन सबूत के साथ वापस नहीं कर सकता।

Comments

यह केवल अर्थ के लिए कुछ javadoc के माध्यम से पढ़ने के लिए पूरी विधि के माध्यम से पढ़ने के बजाय एक विधि का उपयोग करता है

— Heiko Rupp

@ हाइको: यदि आप यह नहीं पता लगा सकते हैं कि फ़ंक्शन नाम और पैरामीटर नामों से क्या कार्य करता है, तो उनका नाम बदलने का समय आ गया है।

— Sjoerd

मैं इस जवाब से सहमत हूं, लेकिन कभी-कभी आपको चीजों के लिए प्रलेखन जोड़ने की आवश्यकता होती है जैसे: वैध रिटर्न मूल्य क्या हैं? मान्य इनपुट मान क्या हैं? यह कार्यक्रम के समग्र ढांचे में कैसे फिट बैठता है? विधि की आवश्यकताएं क्या हैं?

— डोमिनिक मैकडोनेल

@Sjoerd: यह आपको एक व्यापक अवलोकन दे सकता है कि विधि क्या करती है, लेकिन यह आपको सब कुछ नहीं बताता है। स्वीकार्य इनपुट मान, यह क्या वापस कर सकता है, यह त्रुटियों को कैसे संभालता है, यह किस पूर्व स्थिति की अपेक्षा करता है आदि सभी उचित विधि और पैरामीटर नाम चुनकर प्रदान करना असंभव है।

— आनन।

@ तोप: यदि इसे पूर्व स्थिति की आवश्यकता होती है, तो इसे फिर से डिज़ाइन करने का समय है। अपवादों को फेंकने से त्रुटियों को नियंत्रित किया जाता है (और जावा प्रकारों को सूचीबद्ध करेगा - सी ++ और सी # प्रोग्रामर अपवाद प्रकार के बारे में परवाह नहीं करते हैं इसलिए इसे दस्तावेज़ करने की कोई आवश्यकता नहीं है)। एकमात्र महत्वपूर्ण चीज के बारे में यह है कि क्या नल को स्वीकार किया जाता है या वापस लौटाया जाता है (जो C ++ में संदर्भ या संकेत का उपयोग करके संकेत दिया जा सकता है - जावा इस मामले में कम स्पष्ट और आवश्यक दस्तावेज है)। और उस मामले में भी, नाम मदद कर सकते हैं: उदाहरण के लिए FindFoo () नहीं मिला तो अशक्त हो जाता है, GetFoo () नहीं मिला तो अपवाद छोड़ देगा।

— २३:३६

Answer 3

मेरे पास उद्धृत करने के लिए कोई अध्ययन नहीं है, लेकिन मेरे पास एक सरल नियम है: यदि मैं दो सप्ताह बाद अपने कोड पर वापस आता हूं और तुरंत पता नहीं लगा सकता कि मैंने क्या किया, तो इसे या तो टिप्पणियों की आवश्यकता है, या इसे सरल बनाने की आवश्यकता है ।

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

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

Answer 4

किसी भी एपीआई पर जो कोड में एपीआई को थोड़ा गैर तुच्छ दस्तावेज है बेकार है। ऐसा इसलिए है क्योंकि एपीआई में शक्ति एक पूरी इकाई के रूप में एक साथ काम करती है (न कि व्यक्तिगत तरीके / वस्तुएं कैसे काम करती हैं) से आती है।

इस प्रकार असली दस्तावेज की तुलना में अधिक उपयोगी एक कुकबुक जैसा दस्तावेज है जो एपीआई के अपेक्षित उपयोग पैटर्न की व्याख्या करता है, और कुछ स्पष्ट स्थितियों को हल करने के तरीके (जो कि एपीआई के बहुमत (100% का उपयोग नहीं करते हैं) का उदाहरण)।

Comments

उपयोग पैटर्न के लिए +1। अगर मेरे पास काम करने के लिए और कुछ नहीं था, तो कोड नमूने पर्याप्त होंगे।

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

+1 उत्कृष्ट बिंदु के लिए कि शायद कोड उदाहरण एक स्वच्छ एपीआई की तुलना में अधिक महत्वपूर्ण हैं।

— JT

@JT: मुझे भावुकता पसंद है लेकिन मैं इसे फिर से समझना चाहूंगा:Clean common usage scenarios are more important than a clean API

— मार्टिन यॉर्क

Answer 5

एक दिया गया तरीका क्या है, इसका निर्णय उन औजारों के बिना किया गया है, जिनका आविष्कार संभवत: अभी तक नहीं किया गया है, इसलिए बहुत जरूरी है कि उस दस्तावेज को लिखा जाए।

किसी भी सर्वोत्तम-अनुमान प्रथा, जैसे "सभी सार्वजनिक तरीके" या किसी दिए गए पैकेज में सभी कक्षाएं, आदि, मदद कर सकती हैं लेकिन विशिष्ट उपयोग के मामलों से परे सिफारिश करने के लिए बहुत कठिन हैं।

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

(बारीकी से संबंधित: क्या कोडिंग मानकों में बहुत अधिक एकरूपता हो सकती है? )

---

^{माफी जो मेरे पास बोली जाने के लिए कोई अध्ययन नहीं है, लेकिन मुझे संदेह है कि यह एक समस्या है जहां इसे मापने का कोई भी प्रयास सामान्य निष्कर्ष निकालने के लिए परिणाम को बहुत प्रभावित करेगा।}

Answer 6

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

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

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

इस विषय पर सेमिनल काम क्लीन कोड है ।

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

Answer 7

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

Comments

+1 यह जानने के लिए कि कोड क्रिया है या नहीं और पर्याप्त है या नहीं इसकी आवश्यकता है या नहीं, यह पता लगाने के लिए तंत्र के रूप में कोड समीक्षा का उपयोग करें। यह भी एक उत्कृष्ट बिंदु है कि एक साफ एपीआई कैसे परीक्षकों को इकाई परीक्षण लिखने में मदद करता है

— JT

Answer 8

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

इसलिए कोड को बहुत अच्छी तरह से टिप्पणी की जानी चाहिए और इसलिए स्व-दस्तावेज कोड होना चाहिए जिसे किसी भी बाहरी दस्तावेज की आवश्यकता नहीं है।

Answer 9

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

कई मामलों में, घोस्टडॉक आपको यह बताना भी शुरू नहीं कर सकता है कि वास्तव में एक फ़ंक्शन क्या करता है। उस मुद्दे को संबोधित करने में आपका समय बेहतर रूप से व्यतीत होता है और (हो सकता है) घोस्टडॉक से ऑटो तक आपका कोड उत्पन्न हो।

गहरी चर्चा के लिए बॉब मार्टिन से क्लीन कोड और पीपीपी देखें ।