आप अपनी टिप्पणियां कैसे पसंद करते हैं?

Question

टिप्पणियों के लिए आपके सर्वोत्तम अभ्यास क्या हैं? उनका उपयोग कब किया जाना चाहिए, और उनमें क्या होना चाहिए? या टिप्पणियां भी जरूरी हैं?

Answer 1

टिप्पणियां बनाए रखने के लिए आवश्यक हैं। याद रखने का सबसे महत्वपूर्ण बिंदु क्यों है आप कुछ कर रहे हैं, क्या आप कर रहे हैं।

Answer 2

मुझे लगता है कि यह परिदृश्य पर निर्भर करता है।

तरीके/कार्यों/कक्षाओं को वे क्या करते हैं, वे क्या करते हैं, वे क्या करते हैं और वे क्या लौटते हैं, अगर वे तुरंत स्पष्ट नहीं होते हैं और आमतौर पर (मेरे कोड में) एक जावडोक के रूप में आता है स्टाइल टिप्पणी ब्लॉक।

इन-ब्लॉक कोड, मैं लाइनों के एक ब्लॉक के ऊपर एक टिप्पणी छोड़ देता हूं ताकि यह समझाया जा सके कि यह क्या करता है, या लाइन के अंत में एक छोटा और गुप्त कार्य-कॉल है।

Answer 3

स्कूल में, नियम सबकुछ टिप्पणी करना था, ताकि टिप्पणियां कोड से अधिक हो जाएं। मुझे लगता है कि मूर्खतापूर्ण है।

मुझे लगता है कि टिप्पणियों का उपयोग कोड के पीछे "क्यों" दस्तावेज करने के लिए किया जाना चाहिए, न कि "कैसे" ... कोड स्वयं "कैसे" बताता है। यदि कोई ऐसा ऑपरेशन है जो वास्तव में स्पष्ट नहीं है कि यह क्यों किया जाता है, तो यह टिप्पणी के लिए एक अच्छी जगह है।

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

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

Answer 4

टैग खोज का उपयोग करें और आप मिल जाएगा अतः पहले से ही कोड टिप्पणी के बारे में चर्चा का एक ढेर है:

https://stackoverflow.com/questions/tagged/comments

Commenting code

Answer 5

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

Answer 6

अक्सर उत्तर है: यह निर्भर करता है। मुझे लगता है कि अगर आप टिप्पणी लिख चुके हैं तो निर्णय के लिए बहुत महत्वपूर्ण है, अगर टिप्पणी अच्छी या बुरी है। वहाँ टिप्पणी के लिए कई संभावित कारण हैं:

• संरचना स्पष्ट (अर्थात जो पाश यहाँ समाप्त हो गया) बनाने के लिए

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

• समझाने के लिए, क्या कोड

बहुत बुरा करता है: यह खतरनाक मेरी राय में है। अक्सर ऐसा होगा, कि आप बाद में कोड बदलते हैं और टिप्पणी के बारे में भूल जाते हैं। अब टिप्पणी गलत है। यह बहुत बुरा है।

• एक समाधान इंगित करने के लिए/एक bugfix

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

प्रलेखन-प्रयोजनों के लिए

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

Answer 7

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

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

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

Answer 8

Code Complete पर एक नज़र डालें। इस तरह के विषयों के लिए यह सबसे अच्छा है।

Answer 9

बस कुछ टिप्पणी:

टिप्पणियाँ सब कुछ आसानी से कोड (जैसे जटिल गणितीय एल्गोरिदम) से नहीं लगाया जा सकता है कि के लिए महत्वपूर्ण हैं।

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

मुझे पसंद नहीं है टिप्पणियां इस तरह:

// Create the "Analyze" button 
Button analyzeButton = new Button(); 
analyzeButton.Text = "Analyze"; 
analyzeButton.Location = new Point(100, 100); 
Controls.Add(analyzeButton); 

बेहतर:

CreateAnalyzeButton(); 


void CreateAnalyzeButton() 
{ 
    Button analyzeButton = new Button(); 
    analyzeButton.Text = "Analyze"; 
    analyzeButton.Location = new Point(100, 100); 
    Controls.Add(analyzeButton); 
} 

अब कोड पूरी कहानी कहता है। टिप्पणी के लिए कोई ज़रूरत नहीं है।