क्या आपको लगता है कि कोड स्वयं दस्तावेज है? [बन्द है]

24

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

6 साल पहले बंद हुआ ।

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

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

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

source-code

— डिसलेट प्लैनेट
स्रोत

6

मैं हां या नहीं के जवाब से नहीं सीखता, मैं ऐसे सवाल का काला या सफेद जवाब देने से सीखता हूं। मेरा जवाब होगा नहीं। नौकरी के लिए।

— मौविइल

12

निश्चित रूप से मुझे आपका प्रश्न नहीं मिलता है, "सेल्फ डॉक्यूमेंटिंग कोड" आमतौर पर अच्छी तरह से लिखा और समझने में आसान (आशय) कोड का वर्णन करता है, वास्तव में प्रगति से संबंधित नहीं है ... कुछ डेवलपर्स टिप्पणी कोड के बजाय इस दृष्टिकोण का उपयोग करते हैं ...

— निम

1

@Nim - टिप्पणियों आदि के अलावा अधिक बार , लेकिन +1 वह टिप्पणी करता है।

— स्टीव 314

1

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

— उजाड़ ग्रह

1

@ सच, मैं चाहता हूं कि ऐसा ही हो .. <sigh />

— Nim

50

आंशिक रूप से।

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

की तुलना करें:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

लेकिन आप अभी भी नहीं जानते हैं कि एक कार क्यों शुरू की जा रही है। इसलिए, केवल आंशिक रूप से। यह बहुत ही भयानक है कि आपका साक्षात्कारकर्ता एक काले और सफेद उत्तर की उम्मीद कर रहा था, जब तक कि काले और सफेद के उनके विचार में बहुत मजबूत शामिल नहीं था।

— मार्क कैनलास
स्रोत

7

+1 कोड जो बताता है कि अभी भी हो रहा है वह यह नहीं समझा सकता है कि ऐसा क्यों हो रहा है (और कुछ अन्य तरीके से नहीं)।

— FrustratedWithFormsDesigner

24

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

— दान मैकग्राथ

9

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

— मेसन व्हीलर

5

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

4

आपको पता होगा कि कार की शुरुआत क्यों की जा रही थी अगर वह बयान InitiateCommuteToWork () या StartPreRaceSequence () नामक फ़ंक्शन में था।

— पेमदास

33

अपने आप में कोड स्व-दस्तावेजीकरण नहीं है।

कारण यह है कि कोड HOW बताता है और WHY के बारे में परवाह नहीं करता है कि कोड को बनाए रखने के लिए मनुष्यों को क्या जानना चाहिए।

इसलिए आपको सभी WHY के स्पष्टीकरण के लिए अतिरिक्त टिप्पणियों की आवश्यकता है । आप अपने चर नामों को निर्णयों के कुछ हिस्से को शामिल करके उन्हें सीमित कर सकते हैं, लेकिन आप उनसे बच नहीं सकते।

— उपयोगकर्ता 1249 को प्रकट करता है
स्रोत

1

++ बिल्कुल सही। टिप्पणियाँ क्यों और कैसे के बीच एक कड़ी होनी चाहिए।

— माइक डनलवे

4

+1 इस बात पर जोर देने के लिए कि टिप्पणियां WHY का जवाब देती हैं, न कि WHAT या HOW का।

— oosterwal

इस जवाब के साथ सवाल समझ में आता है (80% हिस्सा नहीं)।

— उपयोगकर्ता अज्ञात

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

— ग्राम्पमीकी

धन्यवाद, ईमानदारी से यह जोर क्यों बनाम कैसे, अभी, प्रोग्रामिंग के 2 साल बाद, मुझे टिप्पणी कोड का उद्देश्य सिखाया।

— राफेल एम्सॉफ

7

उचित कोड आपको " कैसे " बताता है । उचित टिप्पणियां आपको " क्यों " बताती हैं ।

इसलिए कोड चीजों के हासिल करने के तरीके का स्व-दस्तावेजीकरण हो सकता है, लेकिन आप इसे दस्तावेजों के कारण नहीं मान सकते।

— वाइल्डपीक्स
स्रोत

6

यदि वे काले और सफेद उत्तर पर जोर देते हैं, जिसमें कोई बीच का मैदान नहीं है, तो उत्तर नहीं है।

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

कुछ भी लेकिन कोड का सबसे तुच्छ टुकड़ा कम से कम कुछ बाहरी प्रलेखन से लाभ उठा सकता है।

— जेरी कॉफ़िन
स्रोत

5

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

उस ने कहा, कोड को स्पष्ट करके क्या किया जा सकता है, इसकी सीमाएँ हैं। उन मामलों में, आपको दस्तावेज़ चाहिए।

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

टिप्पणी करने के गुण और नुकसान पर एक दिलचस्प बातचीत के लिए , http://www.perlmonks.org/index.pl?node_id=65153 एक पुरानी बातचीत के लिए देखें जिसका मैं हिस्सा था। (ध्यान दें, उस समय हमारे पास वह वार्तालाप था, चैट का एक निजी सेट था जो मित्रतापूर्ण था। मुझे हमेशा इस बात का पछतावा है कि बातचीत का केवल अधिक नकारात्मक आधा हिस्सा सार्वजनिक है।) मेरी राय अब बिल्कुल वैसी नहीं है जैसा मैंने सोचा था। , लेकिन मुझे अभी भी लगता है कि बातचीत में विचार के लिए सार्थक भोजन है।

— btilly
स्रोत

1

+1 के लिए "दस्तावेज़ीकरण में गलतियों को छोड़ दिया जाता है", हालांकि यह वास्तव में बहुत दूर नहीं जाता है। यह अधिक पसंद है "दस्तावेज़ों में गलतियों को वर्षों बाद तक ध्यान नहीं दिया जाता है जब कोई नोटिस करता है कि वे कोड से मेल नहीं खाते हैं"।

— लैरी कोलमैन

5

मुझे लगता है कि यह सवाल बहुत सामने आता है, और अक्सर इसके बारे में एक धार्मिक उत्साह होता है। यहाँ इस पर मेरा लेना है ...

एक आदर्श दुनिया में निम्नलिखित कथन किया जा सकता है:

कोड को इस तरह से लिखा जाना चाहिए, कि टिप्पणी की आवश्यकता के बिना तर्क का पालन किया जा सके।

ठीक है, यह काफी उचित है, लेकिन समस्या यह है कि हम एक आदर्श दुनिया में नहीं रहते हैं। इस आदर्श कथन को प्राप्त करने के साथ कुछ मुद्दे हैं।

प्रोग्रामर अक्सर उस उद्योग के विशेषज्ञ नहीं होते हैं जिसके खिलाफ वे प्रोग्रामिंग कर रहे हैं। किसी फ़ंक्शन को समझना काफी आसान है जैसे startEngine(Car car)(अधिकांश) हर कोई समझ सकता है कि यहां क्या पूछा जा रहा है। लेकिन असली दुनिया में चले जाओ, और चीजें थोड़ी फीकी पड़ती हैं। उदाहरण के लिए फ़ंक्शन getSess(String tid, String aid)पूरी तरह से एक ट्रांसपोर्ट इंजीनियर के लिए समझ में आता है जो डीडब्ल्यूडीएम सिस्टम को समझता है, लेकिन यह प्रोजेक्ट पर लगाए गए नए प्रोग्रामर के लिए एक चुनौती पेश कर सकता है। अच्छी तरह से रखी गई टिप्पणियाँ कोड को समय पर समझने में संक्रमण को कम करने में मदद कर सकती हैं।
प्रोग्रामर ने कोड को बनाए रखने के लिए कहा, अक्सर कोड के मूल आर्किटेक्ट के रूप में कुशल नहीं होते हैं। मूल प्रोग्रामर एक विशिष्ट कार्य को पूरा करने के लिए तेज, रसीला, कुशल एल्गोरिदम लिखने के लिए पर्याप्त कुशल हो सकता है। लेकिन प्रोग्रामर ने उस कोड को बनाए रखने का काम किया, जो समझने की कोशिश कर रहा है कि क्या हो रहा है। अच्छी तरह से रखी गई टिप्पणियां कोड को समय पर समझने में संक्रमण को कम करने में मदद कर सकती हैं।
आपने कितनी बार कोड लिखा है, कि आपने बाद में यह समझने के लिए संघर्ष किया कि आपने ऐसा क्यों किया, या यहां तक कि आप क्या हासिल करने की कोशिश कर रहे थे? हम सभी समय-समय पर ऐसा करते हैं। एक समस्या का समाधान, और एक समस्या के समाधान के लिए एक आसान पालन करना अक्सर दो अलग-अलग मानसिकताएं होती हैं। जब तक आप वह व्यक्ति नहीं हैं जो गेट के बाहर पूरी तरह से कोड लिख सकता है, तो आप अक्सर अपने कोड के साथ बहुत सारे गलत काम करते हैं जैसे आप साथ चलते हैं। तुम भी थोड़ी देर के लिए कोड के इस बिट में वापस पाने में सक्षम नहीं हो सकता है। अच्छी तरह से रखी गई टिप्पणियां कोड को समय पर समझने में संक्रमण को कम करने में मदद कर सकती हैं।
अद्वितीय स्थितियों में स्पष्टीकरण की आवश्यकता होती है। उदाहरण के लिए एक प्रोग्रामर आश्चर्यचकित हो सकता है कि डीडब्लूडीएम डिवाइस के साथ संचार करने के लिए एक 100ms का ठहराव क्यों रखा गया था। अगले प्रोग्रामर को यह बताने दें कि डिवाइस को धीमा होने के कारण एक ठहराव की आवश्यकता है, और याद कर सकते हैं कि कमांड में जानकारी का एक मूल्यवान बिट होगा। अच्छी तरह से रखी गई टिप्पणियां कोड को समय पर समझने में संक्रमण को कम करने में मदद कर सकती हैं।

अच्छी तरह से लिखा गया है, "स्व-दस्तावेजीकरण" कोड खोजने के लिए एक खुशी है। अच्छी तरह से रखा गया है, अच्छी तरह से रखा गया है, "स्व-दस्तावेजीकरण" कोड के साथ अच्छी तरह से लिखा गया है, यह एक बहुत ही दुर्लभ खोज है।

— बिल
स्रोत

4

प्रारंभिक प्रश्न के प्रत्येक पक्ष पर तर्क देने के लिए:

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

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

पूछने का बिंदु: क्या आप किसी उत्तर की सीमाओं को पहचानते हुए आंशिक जवाब देंगे या आप आँख बंद करके जिस पर भी विश्वास करते हैं वह बेहतर अभ्यास है? यदि आपके हां या ना में आपके जवाब में कितना यकीन है? इसे एक तनावपूर्ण प्रश्न के रूप में देखा जा सकता है जिसे किसी ऐसे व्यक्ति से बाहर निकलने के लिए डिज़ाइन किया गया है जो उत्तर दे सकता है, "क्या ...? यह सबसे विनम्र प्रश्न जो आप मुझसे कभी पूछ सकते हैं। मैं इस आधार पर जवाब देने से इनकार करता हूं कि यह अपमान करता है। विश्वास से परे मेरी बुद्धि! " बल्कि एक घमंडी और गर्वित जवाब के रूप में कि मैं कुछ लोगों को उस स्वर के साथ जवाब देने के लिए तस्वीर दे सकता था।

— जेबी किंग
स्रोत

4

जाहिर है कि वह नूत की शैली में एक साक्षर प्रोग्रामर थे। एल.पी. शिष्य के लिए कोड को मान्य होने के लिए स्व-दस्तावेज होना चाहिए। तो एकमात्र संभव उत्तर "हां" है।

यहां समस्या यह है कि कई साक्षर प्रोग्रामिंग भाषाएं नहीं हैं और कोई भी नहीं जिसे मैं व्यापक व्यावसायिक उपयोग के बारे में जानता हूं। तो यह कहीं न कहीं एक आला स्थिति होगी।

— М ס ž
स्रोत

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

— पीटरअलेनवेब

3

मुझे लगता है कि साक्षात्कारकर्ता की तलाश क्या हो सकती है: "आप स्व दस्तावेज कोड कैसे लिखते हैं?" एक निहितार्थ के साथ "प्रलेखन के प्रति आपका दृष्टिकोण क्या है?"

मैं रॉबर्ट सी मार्टिन नाम के एक व्यक्ति द्वारा वास्तव में एक प्रेरणादायक व्याख्यान में गया था, जहां उन्होंने एक बार अपने स्वच्छ कोड के 'लेखन विधियों' अध्याय के बारे में बात की थी।

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

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

आप पठनीय, कुछ हद तक स्व-दस्तावेजीकरण कोड (जब तक आप संक्षिप्त, अभी तक वर्णनात्मक नाम) में प्रयास करते हैं, जो समझना और बनाए रखना आसान है।

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

— मैट
स्रोत

3

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

— पेम्दास
स्रोत

2

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

तो हाँ कोड स्व-दस्तावेजीकरण है। कितनी अच्छी तरह से प्रलेखित है यह एक और सवाल है।

— माइकल ब्राउन
स्रोत

2

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

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

— पॉल नाथन
स्रोत

++ अगर पाठक के वातावरण से आपका मतलब है कि पाठक डोमेन और प्रोग्रामिंग तकनीकों के बारे में कितना जानता है, तो मैं आपके साथ 100% हूं।

— माइक डनलैवी

डोमेन, तकनीक, उस भाषा को पढ़ने की क्षमता - यह सब।

— पॉल नाथन

2

मुझे पता है कि उस सवाल का जवाब ज्यादातर लोगों को "नहीं" होगा, लेकिन मैं हां कहने जा रहा हूं। अगर मुझे नौकरी के लिए एक साक्षात्कार में पूछा गया, तो मैं अभी भी हां कहूंगा।

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

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

— ProdigySim
स्रोत

2

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

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

— ब्रायन
स्रोत

2

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

— SnoopDougieDoug
स्रोत

+1। बहुत बार कोड लिखने के लिए पठनीयता के पहलू को कम समय के लिए कारोबार किया जाता है। व्यवहार में कोड लिखने की तुलना में पढ़ने पर अधिक समय खर्च किया जाएगा।

— शेड्यूलर

1

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

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

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

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

— UML_GURU
स्रोत