क्या टिप्पणियों को प्रलेखन का एक रूप माना जाता है?

11

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

यह नहीं होगा:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

प्रलेखन माना जाता है, खासकर अगर एक डेवलपर मेरे कोड का उपयोग कर रहा है? या प्रलेखन को कोड के बाहर माना जाता है?

documentation comments

— गतिशील
स्रोत

11

यदि आप JavaDocs या Doxygen जैसे डॉक्यूमेंट जनरेशन सिस्टम का उपयोग कर रहे हैं, तो टिप्पणियाँ शाब्दिक रूप से प्रलेखन हैं।

— रोबोट

5

YANGNI ( xprogramming.com/Practices/PracNotNeed.html )। अपनी संतुष्टि के लिए अपने कोड का दस्तावेज़ दें। ग्राहक को (यदि कोई एक है) तो आप उनकी संतुष्टि के लिए दस्तावेज लिखने के लिए भुगतान करें। इस बारे में चिंता न करें कि आप कितने लोगों से कहने के लिए बात करते हैं (जब तक कि वे आपको भुगतान नहीं करते हैं)।

— एमोरी

1

आपकी 2 टिप्पणियों में से 2 बेकार है, क्यों $ फू को बार से प्रतिस्थापित न करें। अगर यह सच नहीं है तो टिप्पणी गलत है। पहली टिप्पणी गलत है। यह एक असाइनमेंट है।

— ctrl-alt-delor

2

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

— ctrl-alt-delor

2

YANGNI "आपको इसकी आवश्यकता नहीं है"

— क्रिस एस

27

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

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

— Oleksi
स्रोत

3

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

— एडवर्ड स्ट्रेंज

2

मैं वास्तव में इस बात से असहमत हूं, क्योंकि आपके पास एकमात्र विश्वसनीय दस्तावेज स्रोत कोड ही है। दोनों टिप्पणियों और "प्रलेखन" को कोड के साथ बनाए रखा जाना चाहिए, जो शायद ही कभी होता है। तो प्रलेखन का एकमात्र विश्वसनीय स्रोत आपका कोड है!

— शहादत

3

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

— ओलेक्सी

3

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

— डोनल फेलो

3

यह भी ध्यान दें कि टिप्पणियों, कई भाषाओं में, वास्तविक प्रलेखन उत्पन्न करने के लिए उपयोग की जाती हैं ... इसलिए वे अक्सर एक ही होती हैं। मिसाल के तौर पर MSDN देखें।

— स्टीवन एवर्स

12

वे दस्तावेज़ीकरण का एक रूप हैं, लेकिन याद रखें कि प्रलेखन देखने वाले की नज़र में है ...।

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

तो असली सवाल यह है कि आपका ग्राहक कौन है? यदि आप हैं, तो स्व दस्तावेज कोड या टिप्पणियां पर्याप्त हैं। यदि यह किसी और के लिए है, तो हो सकता है कि आप दस्तावेज़ को विस्तृत करना चाहें।

— MathAttack
स्रोत

17

स्व दस्तावेज कोड एक झूठ है।

— यानिस

1

@YannisRizos एक स्पष्ट झूठ की तुलना में एक अप्राप्य लक्ष्य की तरह है।

— पथराइन की लौ

2

@YannisRizos: आप सही हो सकते हैं, लेकिन जिस कोड को बहुत सारी टिप्पणियों की आवश्यकता होती है, वह लगभग कभी बहुत बुरा कोड होता है और लगभग कभी भी इस तरीके से लिखा जा सकता है कि उसे कम टिप्पणियों की आवश्यकता होती है।

— डॉक्टर ब्राउन

9

@DocBrown निर्भर करता है। मैंने लोगों को लूप्स के लिए दस्तावेज करते हुए देखा है और मैंने लोगों को यह दावा करते हुए देखा है कि 100 लॉजिक लॉजिक स्व दस्तावेज था। तथ्य यह है कि अत्यधिक टिप्पणियों को चोट नहीं लग सकती है (यदि अप्रचलित / गलत को छोड़कर), और अगर मुझे अत्यधिक टिप्पणी और स्व दस्तावेज कोड के बीच चयन करना है, तो मैं हमेशा पहला चुनूंगा। बेशक, मैं बहुत संतुलित और बिंदु टिप्पणियों को पसंद करता हूं , जैसे ओलेक्सी वर्णन करता है ।

— यनीस

1

@ मैथअटैक अधिकांश सभ्य आईडीई टिप्पणियों को छिपा / मोड़ सकते हैं। लेकिन हाँ, कभी-कभी वे बस रास्ते में मिल जाते हैं।

— यनीस

3

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

मुझे पता है कि आप इसे एक उदाहरण के रूप में फेंक रहे हैं, लेकिन जैसे सामान

print $foo; # this prints "bar"

उपयोगी नहीं है; यह सिर्फ दृश्य अव्यवस्था जोड़ता है। स्पष्ट दस्तावेज नहीं है।

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

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

— जॉन बोडे
स्रोत

3

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

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

... पढ़ने बनाम लिखने में बिताए समय का अनुपात 10: 1 से अधिक है। हम नए कोड लिखने के प्रयास के तहत पुराने कोड को लगातार पढ़ रहे हैं।

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

— क्रिस एस
स्रोत

2

डॉक्यूमेंटेशन हाउ द नॉट द हाउ का दस्तावेज होना चाहिए । कैसे स्वयं-सिद्ध कोड, है कि में हो जब तक कि यह कुछ रहस्यमय अनुकूलन चाल या अन्य भाषा विशिष्ट तकनीक है जो सामान्य रूप से उत्पन्न नहीं है चाहिए।

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

1

सचमुच मुश्किल सामान एक अकादमिक पेपर (या, कभी-कभी, पेटेंट) में होना चाहिए।

— डोनल फेलो

2

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

ऐसा लगता है जैसे आप चीजों को अनिवार्य रूप से टिप्पणी करते हैं। अन्य विकल्प होना एक अच्छी बात हो सकती है। मैं प्रलेखन के तीन श्रेष्ठ रूपों के बारे में सोच सकता हूँ:

1) अपने कोड को बेहतर तरीके से फैक्टर करें। टिप्पणी में जोड़ने के बजाय, एक विधि या फ़ंक्शन निकालें जिसका नाम उस टिप्पणी का पाठ है जिसे आप लिखने जा रहे थे। तो कोड कहता है कि आपकी टिप्पणी क्या कहने वाली थी।

2) टेस्ट। यह प्रलेखन का रूप है जिसे मैं आमतौर पर खोजता हूं। इकाई परीक्षण और स्वीकृति परीक्षण जीवित दस्तावेज हैं, और आसानी से पढ़ सकते हैं यदि बहुत सारे सार्थक तरीके इरादे व्यक्त करने के लिए उपयोग किए जाते हैं, जैसे कि बिंदु 1 में।

3) स्क्रिप्ट के लिए, --help विकल्प। यह वह जगह है जहां आप डॉक्टर पर पागल हो सकते हैं। उदाहरणों में छड़ी, पूर्वानुमान करें कि उपयोगकर्ता को क्या आवश्यकता होगी।

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

— माइक होगन
स्रोत