"टिप्पणियाँ एक कोड गंध हैं" [बंद]


100

मेरा एक सहकर्मी का मानना है कि किसी भी इन-कोड टिप्पणियों के उपयोग (यानी, नहीं जावाडोक शैली विधि या कक्षा टिप्पणियां) एक है कोड गंध । तुम क्या सोचते हो?


44
मैं किसी भी उत्तर को उत्कीर्ण करने जा रहा हूं जो "नहीं" कहता है।
निकोल

2
@ उत्पत्ति यह देवत्व की गंध है।
ixtmixilix

107
आपके सहकर्मी एक व्यापक सामान्यीकरण है, जो बनाया स्वचालित रूप से वह गलत है का मतलब है। :)
एलेक्स फीनमैन

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

5
@ एलेक्स, यह एक व्यापक सामान्यीकरण नहीं है, जो इसलिए गलत है (जिसके परिणामस्वरूप वह वैसे भी गलत नहीं है)?

जवाबों:


167

केवल अगर टिप्पणी बताती है कि कोड क्या कर रहा है।

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

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

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

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


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

1
वैसे भी, कभी-कभी आपको यह भी बताना होगा कि अगर यह जटिल है (विशेष रूप से यदि यह अनुकूलित है या किसी अन्य प्रकार के गैर-तुच्छ कार्यों के लिए है)। अगर मुझे यह समझने के लिए कोड के एक ब्लॉक को पढ़ने में 5 मिनट से अधिक समय
लगाना है

3
"केवल अगर टिप्पणी बताती है कि कोड क्या कर रहा है।" या यदि टिप्पणी बताती है कि कोड क्या करता था; कोड बदल गया है लेकिन टिप्पणी नहीं है।
ब्रूस एल्डरमैन

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

2
@ back2dos, यदि आप अक्सर अन्य लोगों के कोड को पढ़ते समय उल्टी करते हैं, तो मुझे खुशी है कि हम कार्यालय साझा नहीं कर रहे हैं ...

110

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

आपका सहकर्मी पर्याप्त अनुभव नहीं है, जाहिर है।


16
मैं "अच्छी तरह से नामित, बहुत साफ, अनलंकृत कोड" को देखने के लिए उत्सुक हूं जिसका पालन करना कठिन है। कोई भी कोड जिसे मैं वर्गीकृत करूँगा, उसका पालन करना बहुत आसान है। मैं निश्चित रूप से जहाँ तक "आपका सहकर्मी पर्याप्त अनुभवी नहीं है, जाहिर है" नहीं जाएगा।
लिग्गी

8
@ लिगी: मैं करूंगा। यह एक शोध एल्गोरिथ्म है, लाइन-ऑफ-बिजनेस एप्लिकेशन नहीं है।
पॉल नाथन

9
मेरे पास एक बार कोड का एक टुकड़ा था जहां आपको एक डेटाबेस कॉलम ऑब्जेक्ट (3rd पार्टी) को "गलत" क्रम (प्रक्रिया और "कोडिंग मानकों के" तर्क "द्वारा परिभाषित) में करना था - इसे उस क्रम में करें 'आमतौर पर इस्तेमाल होता है और यह दुर्घटनाग्रस्त हो जाएगा। कोड को पढ़ने की कोई भी मात्रा आपको यह नहीं बता सकती है, इसलिए यह पूरी तरह से, एक टिप्पणी थी - और यह एक गंध नहीं थी, कम से कम उस कोड में नहीं जिस पर हमारा नियंत्रण था (जो नीचे की रेखा है)। टिप्पणियों की एक पूरी और पूरी तरह से कमी उतनी ही गंध है जितनी खराब टिप्पणियां।
मर्फ़

29
गणित, गणित, गणित। नहीं सभी कोड तुच्छ IoC गोंद और 'मूल्य * मात्रा' लागू करते हैं। जटिल गणित को स्व-व्याख्या करने के लिए जादुई रूप से नहीं बनाया जा सकता है।
23

4
@ लिग्गी, कोड को जटिल डेटास्ट्रक्चर लागू करना व्यापक प्रलेखन के बिना पूरी तरह से समझ से बाहर हो सकता है।

75

टिप्पणियों में बताया जाना चाहिए कि क्यों, कैसे नहीं।

Howप्रकार की टिप्पणियां आमतौर पर रिफ्लेक्टरिंग का उपयोग करने से बेहतर होती हैं। व्यक्तिगत रूप से, मैं आमतौर पर टिप्पणियों के पक्ष में टिप्पणियों से बचता हूं।

इससे पहले:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

उपरांत:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

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

3
अच्छा उदाहरण है, लेकिन सिस्टम डॉलर के विपरीत सेंट के साथ काम क्यों कर रहा है? यह प्रश्न वित्तीय प्रणालियों में प्रासंगिक हो जाता है, जहाँ आप देख सकते हैं कि आंशिक मुद्रा चलन में है।
rjzii

3
@ फंक्शन के नाम को कहना चाहिए कि यह क्या करता है।
एल्ब

3
@GSto, मैं और अधिक असहमत नहीं कर सका। यदि कोड जटिल है, तो इसे उन छोटे तरीकों / कार्यों में तोड़ दिया जाना चाहिए जो उपयुक्त नामों के साथ हैं जो कार्रवाई का वर्णन करते हैं।
कैफीक

1
आप मानते हैं, कि कोड आधार पर आपका पूर्ण नियंत्रण है।
LennyProgrammers

32

मैं आपके सहकर्मी को विधर्मी घोषित करता हूँ! मेरे विधर्मी-जलने के जूते कहाँ हैं?

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

मैं जिस कोड पर काम कर रहा हूं, उससे कुछ वास्तविक टिप्पणियां:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.


7
अच्छी टिप्पणियों के लिए +1। कोई भी कोड यह नहीं कह सकता है कि "यदि ऐसा होता है, तो डेटाबेस की परिभाषा के साथ किसी का चक्कर चल रहा है"।
डिस्टैंट इको

9
@ निफ़रा, ठीक है, हम एक फेंक सकते हैंSomebodyScrewedAroundWithDatabaseException ...

@ Thorbjørn +1, यदि कोड जानता है कि क्या गलत है, तो अच्छी तरह से रिपोर्ट करें। ग्राहक टेक का समर्थन करते हैं और संभवत: अपने डीबी को पुनः लोड कर सकते हैं, और सेवा कॉल से बच सकते हैं।
टिम विलक्रॉफ्ट

@ टिम, जैसा कि ग्राहक यह देख सकते हैं, एक अधिक तटस्थ नामकरण उपयुक्त हो सकता है।

3
ज़रूर याद रखें: कभी भी मूर्खतापूर्ण नामों का इस्तेमाल न करें। ग्राहक हमेशा उन्हें देखेगा।
टिम विलिसक्रॉफ्ट

29

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

आपको पूरी तरह से बचना चाहिए "टिप्पणी-कोड अतिरेक" (टिप्पणियाँ जो कोड में कुछ भी नहीं जोड़ता है):

i++; // Increment i by 1

फिर, यदि एक अच्छा (और अनुरक्षित / संरेखित) कोड डिज़ाइन और प्रलेखन है, तो टिप्पणी करना और भी कम उपयोगी है।

लेकिन कुछ परिस्थितियों में टिप्पणी कोड पठनीयता में एक अच्छी सहायता हो सकती है:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

मत भूलो कि आपको बनाए रखना है और सिंक में भी रखना है टिप्पणी ... पुरानी या गलत टिप्पणियाँ एक भयानक दर्द हो सकती हैं! और, एक सामान्य नियम के रूप में, बहुत अधिक टिप्पणी करना खराब प्रोग्रामिंग का लक्षण हो सकता है।


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

81
मुझे नफरत है जब लोग आपके प्रश्न में उस दूसरे उदाहरण का उपयोग करते हैं। } //end whileबस इसका मतलब है कि लूप की शुरुआत इतनी दूर है, आप इसे देख भी नहीं सकते हैं, और कोई संकेत नहीं हैं कि जिस कोड को आप देख रहे हैं वह लूप में है। कोड को संरचित करने के तरीके के बारे में टिप्पणियों के लिए भारी रिफैक्टिंग को गंभीरता से पसंद किया जाना चाहिए।
कार्सन मायर्स

4
@ कर्सन: ब्लॉक को कम रखने के दौरान एक प्रसिद्ध नियम है, इसका मतलब यह नहीं है कि हम हमेशा इसे लागू कर सकते हैं।
जादूगर '

4
@ कारसन: जिन परियोजनाओं पर मैं काम करता हूं उनमें से एक में अपर्याप्त कोड की समीक्षा है, जो "ओएमएफजी जस्ट किल योरसेल्फ" के एक चक्रीय जटिलता के साथ जेएसपी का एक संग्रह है। खूनी चीजों को फिर से दिखाना उन दिनों के काम का प्रतिनिधित्व करता है, जिन्हें कहीं और खर्च करने की जरूरत होती है। वे } // end whileटिप्पणियां जीवनरक्षक हो सकती हैं।
ब्लेयरहिपो

11
@ ब्लेयरहिपो: "[ए] कोड गंध किसी प्रोग्राम के स्रोत कोड में कोई लक्षण है जो संभवतः एक गहरी समस्या को इंगित करता है"। बेशक टिप्पणी एक जीवन रक्षक है, लेकिन OMGWTF- पाश उक्त "गहरी समस्या" है और जीवन रक्षक की आवश्यकता एक स्पष्ट संकेतक है;)
back2dos

26

स्पष्ट रूप से "कोड गंध" के रूप में एक विधि या प्रक्रिया को परिभाषित करना एक "ज़ीलोट्री गंध" है। यह शब्द नया "हानिकारक माना" बन रहा है।

कृपया याद रखें कि इन सभी प्रकार की चीजों को दिशानिर्देश माना जाता है।

अन्य जवाबों में से कई अच्छी सलाह देते हैं जब टिप्पणियों को वारंट किया जाता है।

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

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

टिप्पणियां रन टाइम को प्रभावित नहीं करती हैं, इसलिए विचार करने के लिए केवल नकारात्मक मुद्दा रखरखाव है।


8
मुझे लगा कि "एंटी-पैटर्न" नया "हानिकारक माना जाता है" था। एक कोड गंध बस कुछ है जो संभव सफाई के लिए एक करीबी समीक्षा की आवश्यकता है।
जेफरी हेंटिन

1
मैं इस बात से असहमत नहीं हूं कि विरोधी पैटर्न भी योग्य है। वे दोनों इस तरह से उपयोग करते हैं कि गंध के बजाय विरोधी पैटर्न का उपयोग किया जाता है जब डिजाइन पर्याप्त जटिल होता है कि यह स्पष्ट रूप से एक जानबूझकर पसंद है। किसी भी मामले में मैं इस अवधारणा से असहमत हूं कि इन चीजों पर सही का एक पूर्ण स्रोत है।
बिल

4
+1 के लिए "जब तक किंडरगार्टनर समझ सकता है, तब तक सब कुछ रिफलेक्ट करना संभवत: आपके समय का कुशल उपयोग नहीं है, और संभवत: अधिक संक्षिप्त संस्करण भी नहीं करेगा।"
5

23

कुछ मामलों में, अच्छा नामकरण, रीफैक्टरिंग आदि की कोई राशि टिप्पणी को प्रतिस्थापित नहीं कर सकती है। इस वास्तविक दुनिया के उदाहरण को देखें (भाषा ग्रूवी है):

  response.contentType="text/html"
  render '{"success":true}'

अजीब लग रहा है, है ना? शायद एक कॉपी-पेस्ट-त्रुटि? बगफिक्स के लिए प्रयास करता है?

अब टिप्पणियों के साथ भी ऐसा ही:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

function Prime_extjs_uploadform () {response.contentType = 'text / html'; "{" सफलता ": सच्चा} '; } Prime_extjs_uploadform ();
DrPizza

23

यहां प्राथमिक मुद्दा "कोड गंध" शब्द का अर्थ है।

बहुत से लोग (आपके सहित, मुझे लगता है) एक कोड गंध को एक त्रुटि के करीब होने के लिए या कम से कम कुछ ऐसी चीज़ों को समझता है जिसे ठीक करने की आवश्यकता है। शायद आप इसे "एंटी-पैटर्न" का पर्याय मानते हैं।

यह शब्द का अर्थ नहीं है!

कोड गंध रूपक वार्ड विकी से निकलता है , और वे तनाव देते हैं:

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

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

वह यह है कि यह कोड गंध होने के लिए टिप्पणियों का क्या मतलब है।

संपादित करें: मैं सिर्फ इन दो लेखों पर स्तब्ध हूं, जो इसे मुझसे बेहतर बताते हैं:


2
मैं स्तब्ध हूं कि इस जवाब के आने में 2 महीने लग गए। यह दर्शाता है कि शब्द की गलतफहमी कितनी व्यापक है।
पॉल बुचर

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

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

यह सही जवाब है।
vidstige

21

मुझे लगता है कि नियम काफी सरल है: अपने कोड को देखकर एक पूर्ण अजनबी की कल्पना करें। आप शायद 5 वर्षों में अपने स्वयं के कोड के लिए एक अजनबी होंगे। इस अजनबी के लिए अपने कोड को समझने के लिए मानसिक प्रयास को कम करने की कोशिश करें।


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

नहीं, आपको एक मनोरोगी की कल्पना करनी चाहिए जो जानता है कि आप कहां रहते हैं: क्या वे आपके कोड को बनाए रखने के लिए खुश होंगे?
रिचर्ड

4
जब मैं अपठनीय कोड देखता हूं तो मैं नियमित रूप से एक मनोरोगी बन जाता हूं।
लेनीप्रोग्रामर्स

3
5 वर्ष? अधिक 5 मिनट की तरह। ;)
एलेक्स फेनमैन

11

सही टिप्पणी करने के लिए एक अच्छा विचार टिप्पणियों को लिखने के साथ शुरू करना है।

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

यह आपको टिप्पणियों से छुटकारा पाने के लिए आसानी से तरीकों को निकालने की अनुमति देता है,
बस कोड को ये बातें बताएं ! देखें कि यह कैसे लिखा जाता है (कट / पेस्ट) बहुत अच्छे तरीके से:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

उन चीजों के लिए जिन्हें अलग नहीं किया जा सकता है केवल तरीके न निकालें और टिप्पणी के तहत कोड लिखें।

यह वही है जो मैं एक न्यूनतम के लिए टिप्पणी करने के लिए एक उपयोगी तरीके के रूप में देखता हूं, प्रत्येक पंक्ति पर टिप्पणी करने के लिए वास्तव में बेकार है ... केवल एक पंक्ति का दस्तावेज़ यदि यह एक जादू मूल्य आरंभीकरण के बारे में है या जहां यह समझ में आता है।

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


1
मैं यह करता हूं। यदि आपको लगता है कि आपको टिप्पणियों की आवश्यकता है, तो मैं इसे प्रतिस्थापन के रूप में आज़माने की सिफारिश कर सकता हूं।
bzlm

10

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



8

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

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

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

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

सैम्स टी योरसेल्फ विज़ुअल सी # 2010 में 24 घंटे , पीपी 348-349।


1
टिप्पणियाँ बासी हो सकती हैं, लेकिन यह सब कुछ है जो एक संकलक या एक इकाई परीक्षण द्वारा सत्यापित नहीं है, जैसे वर्ग, फ़ंक्शन और चर नामों के अर्थ के लिए सच है।
लेनीप्रोग्रामर्स

@ Lenny222: हां, टिप्पणियाँ बासी हो सकती हैं ... जो आमतौर पर आलसी प्रोग्रामर का संकेत है। यदि टिप्पणी यह ​​वर्णन करती है कि एक डिस्कशन क्यों बनाया गया था, तो कोड गणना के लिए एक विशेष एल्गोरिथ्म का उपयोग क्यों करता है, या यह बताता है कि कोड कैसे कार्य करता है, तो टिप्पणी के लिए कोई कारण नहीं है कि कार्यान्वयन को बदलने और टिप्पणी को अपडेट नहीं करने के अलावा कोई और बासी हो जाए। - जो आलसी होने के बराबर है।
स्कॉट डोरमैन

2
मैं सहमत हूँ। मेरा कहना है, बासी होने का एक जोखिम है, हाँ। लेकिन जब मेरे पास एक फ़ंक्शन doBar () है और 3 साल बाद यह "बार नहीं करता है", लेकिन यह "wednesdays को छोड़कर बार और फू को करता है" तो कार्यों का अर्थ भी बासी हो सकता है। और चर नाम। लेकिन मैं आशा करता हूं कि कोई भी इस कारण से कार्यों और चर को सार्थक नाम न दे।
लेनीप्रोग्रामर्स

6

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


6

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


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

4

माननीय उल्लेख का प्रतिमान है:

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


4

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

टिप्पणियों को कोड के इरादे को स्पष्ट करना चाहिए , ताकि अगर कोई गलती हो, तो टिप्पणियों को पढ़ने वाले + कोड को खोजने का एक मौका होता है।

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


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

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

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

3

टिप्पणियाँ जो किसी में डाल दी जाती हैं क्योंकि किसी को लगता है कि एक विधि में 700 लाइनें होना ठीक है।

टिप्पणियाँ जो वहाँ हैं क्योंकि आप जानते हैं कि यदि आप एक टिप्पणी में नहीं डालते हैं, तो कोई एक ही गलती करेगा फिर भी एक गंध है।

टिप्पणियाँ डाल दी क्योंकि कुछ कोड विश्लेषण उपकरण की मांग है कि यह भी एक गंध है।

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


3

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

tl; dr: अपने कोड को बनाए रखने वाला अगला व्यक्ति शायद आपके जैसा देवता न हो।

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

लेकिन इस तरह से दिन और उम्र में आप एक उच्च स्तर के नुकसान का उपयोग नहीं कर रहे हैं?
इयान

2
@ इयान: कार्यक्रम एक आईबीएम-पीसी बूटलोडर है। आप इसे असेंबली के अलावा किसी और चीज़ में नहीं लिख सकते हैं , क्योंकि आपको रैम पर जहां प्रोग्राम कम है, जहाँ आखिरी शॉर्ट दिखाई देता है, और कुछ हार्डवेयर में रुकावट होती है। गंभीरता से, अपने आप को NASM की एक प्रति प्राप्त करें। इसे इकट्ठा करें, इसे फ्लॉपी या यूएसबी स्टिक के बूट सेक्टर पर लिखें और इसे बूट करें। यद्यपि आप शायद पाएंगे कि यह बग के कारण अपेक्षित रूप से काम नहीं करता है। अब बग ढूंढे ... भले ही, मुझे यकीन है कि अब से 20 साल में, लोग एक ही बात पूछेंगे कि यह जावा का एक हिस्सा है।
चींटी

निश्चित रूप से कोड को C या C ++ में लिखा जा सकता है, और बाइनरी C ऑब्जेक्ट कोड और कुछ बाहरी टूल से इकट्ठे होते हैं।
केविन क्लाइन

दुर्भाग्य से नहीं। CodeProject पर इस पृष्ठ पर एक नज़र डालें: codeproject.com/KB/tips/boot-loader.aspx - "उच्च-स्तरीय भाषाओं में आवश्यक निर्देश नहीं हैं"। इतना ही नहीं, लेकिन आपको बूटलोडर में खेलने के लिए केवल 512 बाइट्स मिले हैं। कभी-कभी आपको बस सीधे हार्डवेयर के पास जाना होता है।
एंट

1
असेंबली कोडिंग करते समय, मैं वही करता हूं जो हर कोई करता है - हर एक लाइन पर टिप्पणी करें कि वह क्या कर रहा है। विचाराधीन लाइन में टिप्पणी होती है "चेक इफ लेटर इज लेटर", क्योंकि कोड सी-स्टाइल 0-टर्मिनेटेड स्ट्रिंग्स का उपयोग करता है। उस टिप्पणी के साथ, यह देखना आसान है कि कोड 1 के साथ एक cmp कर रहा है, जिसका अर्थ है कि यह या तो अनंत लूप में फंस जाता है या तब तक कचरा प्रिंट करता है जब तक कि यह RAM में यादृच्छिक 1 को हिट न कर दे। मैंने इस तथ्य के बारे में एक टिप्पणी भी जोड़ दी है कि तार 0-समाप्त थे, जो कोड से स्पष्ट नहीं है। क्या विधानसभा कोडिंग के लिए स्वचालित इकाई परीक्षण जैसी कोई चीज है?
एंट

2

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

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

इसके अलावा, टिप्पणियां "कैविट्स" को जोड़ने में काफी मददगार हैं जैसे "सावधान रहें! यदि इनपुट का प्रारूप ASCII नहीं है, तो इस कोड को बदलना होगा!"


क्या आप समझा सकते हैं कि "टिप्पणियों से आपका क्या मतलब है जो कोड के ब्लॉक को फिर से शुरू करता है"?
मार्क सी

2

इसे पढ़कर मुझे कुछ ऐसी बातें याद आती हैं जो मैंने पहली बार (एक लंबी सूची से, फोटोकॉपी द्वारा संरक्षित) कुछ दशकों पहले पढ़ी थीं:

वास्तविक प्रोग्रामर टिप्पणी नहीं लिखते हैं - अगर यह लिखना कठिन था तो इसे पढ़ना मुश्किल होना चाहिए

बल्कि पुरानी गंध मेथिंक।


2

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

लेकिन ऐसी तुच्छ प्रक्रिया के बारे में क्या कहना है? तो आप अंत में क्लासिक लिख रहे हैं

i++; // add one to the "i" counter.

बस एक सभ्य ग्रेड पाने के लिए और, यदि आप किसी भी तरह से किसी भी तरह के घोंसले के शिकार हैं, तो तुरंत कोड टिप्पणियों का एक बहुत ही कम राय बनाना।

कोड टिप्पणी एक अच्छी बात नहीं है। यह SOMETIMES NECESSARY THING है, और शीर्ष उत्तर में थॉमस ओवेन्स उन स्थितियों का उत्कृष्ट विवरण प्रदान करता है जिनमें यह आवश्यक है। हालांकि, ये स्थितियां शायद ही कभी होमवर्क-प्रकार के असाइनमेंट में फसल होती हैं।

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


+1 इंगित करने के लिए कि खराब टिप्पणी की आदतें शुरुआती प्रोग्रामिंग कक्षाओं से शुरू होती हैं। -1 के निष्कर्ष के लिए कि टिप्पणियाँ केवल एक अंतिम विकल्प हैं।
एशेल्ली

1

बेशक टिप्पणियाँ एक कोड गंध हैं ...

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

"यह करो!" आपके प्रोजेक्ट मैनेजर का कहना है

आप जवाब देते हैं, "यह नहीं किया जा सकता है।"

वे कहते हैं, "फिर हम इसे करने के लिए किसी और को खोज लेंगे।"

आप कहते हैं, "ठीक है, शायद यह किया जा सकता है।"

और फिर अगले दिनों की एक्स संख्या .. सप्ताह .. महीने .. इसे जानने का प्रयास करें। इस प्रक्रिया के दौरान, आप कोशिश करेंगे और असफल रहेंगे, और कोशिश करेंगे और असफल रहेंगे। हम सब यही करते हैं। सही उत्तर दो प्रकार के प्रोग्रामर हैं, जो टिप्पणी करते हैं और जो नहीं करते हैं।

1) जो लोग या तो भविष्य के संदर्भ के लिए दस्तावेज करके अपना काम आसान कर रहे हैं, असफल दिनचर्या पर टिप्पणी करते हैं जो काम नहीं करते थे (जो काम करता है उसे खोजने के बाद गंध उन्हें हटा नहीं रही है।), या टिप्पणी के साथ कोड को तोड़ना। उम्मीद करने के लिए स्वरूपण यह पढ़ने या समझने के लिए थोड़ा आसान बना देता है। सच में, मैं उन्हें दोष नहीं दे सकता। लेकिन अंत में, वे स्नैप करते हैं और फिर आपके पास यह है: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) वे जो या तो सुपर हीरो बनने का नाटक नहीं कर रहे हैं, या एक गुफा में रह रहे हैं । वे बस दूसरों के लिए लापरवाह उपेक्षा करते हैं, स्वयं, और कोड के बारे में कम परवाह कर सकते हैं, या बाद में इसका क्या अर्थ हो सकता है।

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


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

1

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

  1. आपको केस के आधार पर किसी मामले पर कुछ करने की जरूरत है और इसके लिए कोई अच्छा तर्क नहीं है।
  2. कोड एक या दो साल में बदल जाएगा जब कानून बदल जाएंगे और आप इसे फिर से जल्दी से जल्दी ढूंढना चाहते हैं।
  3. किसी ने अतीत में कोड को संपादित किया क्योंकि उन्हें समझ नहीं आया कि कोड क्या कर रहा था।

इसके अलावा, कंपनी की स्टाइल गाइड आपको कुछ निश्चित तरीके से करने के लिए कह सकती है - अगर वे कहते हैं कि आपकी टिप्पणी में यह टिप्पणी हो सकती है कि किसी फ़ंक्शन में कोड के ब्लॉक क्या कर रहे हैं, तो टिप्पणी शामिल करें।


1

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

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

यहां तक ​​कि मैं जिस छोटी सी सजातीय संस्कृति में रहता हूं, उसके अंदर अन्य लोगों के लिए विचारों का संचार करना इतना मुश्किल है। दुर्घटना के अलावा, मानव संचार आमतौर पर विफल रहता है।


0

मुझे आपके सहकर्मी से सहमत होना होगा। मैं हमेशा कहता हूं कि अगर मैं अपना कोड कमेंट करता हूं, तो इसका मतलब है कि मुझे चिंता है कि मैं भविष्य में अपना कोड पता नहीं लगा पाऊंगा । यह एक बुरा संकेत है।

कोड में टिप्पणी छिड़कने का एकमात्र अन्य कारण कुछ ऐसा है जिसे समझ में नहीं आता है।

वे टिप्पणियाँ आमतौर पर कुछ इस तरह का रूप लेती हैं:

//xxx what the heck is this doing??

या

// removed in version 2.0, but back for 2.1, now I'm taking out again

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

सच सच। ऐसे कारण हैं कि अच्छा कोड स्पष्ट नहीं हो सकता है। हालांकि अधिकांश बार कोडिंग में गड़बड़ी हुई है, क्योंकि यह एक अस्पष्ट तरीके से लिखा गया है।
केन

ऐसा लगता है कि आपने एम्बेडेड प्रोसेसर के लिए कोड नहीं लिखा है जहां आपके पास खेलने के लिए केवल 32k है, और चीजें आपको बोली अस्पष्ट करती हैं। टिप्पणियाँ जीवन रक्षक हैं।
जल्‍दी से जल्‍दी से

0

कोड टिप्पणी, जहां लागू हो, फ़ंक्शन तर्कों और रिटर्न की संरचना, संरचना क्षेत्र, यहां तक ​​कि स्थानीय चर भी बहुत आसान हो सकते हैं। मार्स ऑर्बिटर याद रखें!


इकाइयों को चर नामों में बनाने के लिए बेहतर है, इसलिए गरीब प्रोग्रामर को उन्हें याद रखने की आवश्यकता नहीं है। 'डबल लंबाई // मीटर में' के बजाय 'डबल लेंथ_ एम' कहें। सभी के लिए एक अधिक शक्तिशाली भाषा का उपयोग करना है, इसलिए आप बस लंबाई एल कह सकते हैं; बल f; टोक़ टी = एल * एफ; प्रिंट (t.in (Torque.newtonMeter));
केविन क्लाइन

0

यहाँ मेरा नियम-अंगूठा है:

  • कोड लिखें और एक अलग दस्तावेज़ में कोड का एक छोटा सारांश स्टोर करें।
  • कुछ और काम करने के लिए कई दिनों के लिए कोड को अकेला छोड़ दें।
  • कोड पर लौटें। यदि आप तुरंत नहीं समझ सकते कि यह क्या करना है, तो स्रोत फ़ाइल में सारांश जोड़ें।


0

नहीं, टिप्पणियां कोड गंध नहीं हैं, वे सिर्फ एक उपकरण हैं जिसका दुरुपयोग किया जा सकता है।

अच्छी टिप्पणियों के उदाहरण :

// मुझे लगता है कि यह सेमी में है। आगे की जांच की जरूरत है!

// यह एक्स करने का एक चतुर तरीका है

// सूची यहां गैर-रिक्त होने की गारंटी है


तीसरा एक बुरा टिप्पणी IMO है। क्यों नहीं Assert(list.IsEmpty)?
12In में

@CodeInChaos IMO Assert(!list.isEmpty())तीसरी टिप्पणी के रूप में वास्तव में एक अनुबंध नहीं है, लेकिन केवल व्यवहार (यानी "तर्क अवैध है, तो तर्क खाली होने पर फेंक दें") जो किसी भी अन्य प्रोग्राम लॉजिक की तरह यूनिट-परीक्षण किया जाना चाहिए। टिप्पणी के साथ सूक्ष्म अंतर पर ध्यान दें, जो बताता है कि विधि का उपयोग कब किया जा सकता है, लेकिन पूर्व व्यवहार पूरा नहीं होने पर कोई व्यवहार निर्दिष्ट नहीं करता है। टिप्पणी से बेहतर यह भी होगा कि संकलन-समय अनुबंधों को लागू किया जाए। लेकिन यह मेरे उत्तर के दायरे को
एंड्रेस एफ।

आपको Assertएस व्यायाम करने में सक्षम नहीं होना चाहिए , क्योंकि वे उन चीजों का वर्णन करते हैं जो कभी भी नहीं होना चाहिए, भले ही सार्वजनिक एपीआई को अमान्य तर्क मिले।
कोडइन्चोस

@CodeInChaos मैं अपनी राय से मुकर गया। यहाँ Sunacle के बारे में क्या कहना है । लगता है आप सही थे। खैर, आप हर दिन कुछ सीखते हैं!
एंड्रेस एफ।
हमारी साइट का प्रयोग करके, आप स्वीकार करते हैं कि आपने हमारी Cookie Policy और निजता नीति को पढ़ और समझा लिया है।
Licensed under cc by-sa 3.0 with attribution required.