मेरा एक सहकर्मी का मानना है कि किसी भी इन-कोड टिप्पणियों के उपयोग (यानी, नहीं जावाडोक शैली विधि या कक्षा टिप्पणियां) एक है कोड गंध । तुम क्या सोचते हो?
मेरा एक सहकर्मी का मानना है कि किसी भी इन-कोड टिप्पणियों के उपयोग (यानी, नहीं जावाडोक शैली विधि या कक्षा टिप्पणियां) एक है कोड गंध । तुम क्या सोचते हो?
जवाबों:
केवल अगर टिप्पणी बताती है कि कोड क्या कर रहा है।
अगर मैं जानना चाहता था कि एक विधि या ब्लॉक में क्या हो रहा है, तो मैं कोड पढ़ूंगा। मुझे उम्मीद है, वैसे भी, कि किसी भी प्रोजेक्ट पर काम करने वाले किसी भी डेवलपर्स को कम से कम इतना पता है कि विकास भाषा के साथ क्या लिखा है और क्या कर रहा है, इसे पढ़ें।
अत्यधिक अनुकूलन के कुछ मामलों में, आप ऐसी तकनीकों का उपयोग कर सकते हैं जो आपके कोड का क्या कर रहा है, किसी का अनुसरण करना कठिन हो जाता है। इन मामलों में, टिप्पणियों का उपयोग किया जा सकता है और न केवल यह समझाने के लिए इस्तेमाल किया जाना चाहिए कि आपके पास इस तरह के अनुकूलन क्यों हैं, लेकिन कोड क्या कर रहा है। अंगूठे का एक अच्छा नियम कार्यान्वयन कोड से परिचित किसी और (या कई अन्य लोगों) को होगा और आपके कोड को देखेगा - यदि वे क्यों और कैसे दोनों को समझ नहीं सकते हैं, तो आपको दोनों क्यों और क्यों टिप्पणी करनी चाहिए कैसे।
हालाँकि, कोड में स्पष्ट नहीं है कि आपने कुछ क्यों किया है। यदि आप एक दृष्टिकोण लेते हैं जो दूसरों के लिए स्पष्ट नहीं हो सकता है, तो आपके पास एक टिप्पणी होनी चाहिए जो बताती है कि आपने जो निर्णय लिए, वह आपने क्यों किया। मुझे संदेह होगा कि आपको यह भी महसूस नहीं हो सकता है कि कोड समीक्षा जैसी किसी चीज़ के बाद तक एक टिप्पणी की आवश्यकता है, जहां लोग जानना चाहते हैं कि आपने वाई के बजाय एक्स क्यों किया - आप अपने जवाब को कोड में हर किसी के लिए कैप्चर कर सकते हैं जो इसे देखता है भविष्य में।
हालांकि, सबसे महत्वपूर्ण बात यह है कि जब आप अपना कोड बदलते हैं तो अपनी टिप्पणियों को बदलना होगा। यदि आप एक एल्गोरिथ्म को बदलते हैं, तो टिप्पणियों के साथ अपडेट करना सुनिश्चित करें कि आप एल्गोरिथ्म एक्स के साथ वाई पर क्यों चले गए। बासी टिप्पणियां एक और भी बड़ी कोड गंध हैं।
यह इस समय सुनने के लिए विशेष रूप से परेशान है, मैंने इस सप्ताह के अंत में एक शोध एल्गोरिथ्म (जो वास्तव में प्रकाशित नहीं हुआ है) को लागू करते हुए बहुत अच्छी तरह से नामांकित, बहुत साफ, असुविधाजनक कोड को देख रहा है। मैं इसके बारे में उच्च-स्तर से परिचित हूं, मेरे बगल में बैठा लड़का आविष्कारक था, और कोड कुछ साल पहले किसी और ने लिखा था। हम बमुश्किल इसका पालन कर सके ।
आपका सहकर्मी पर्याप्त अनुभव नहीं है, जाहिर है।
टिप्पणियों में बताया जाना चाहिए कि क्यों, कैसे नहीं।
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)
मैं आपके सहकर्मी को विधर्मी घोषित करता हूँ! मेरे विधर्मी-जलने के जूते कहाँ हैं?
जुनूनी टिप्पणी खराब है और एक रखरखाव सिरदर्द है, और टिप्पणियां अच्छी तरह से नामित विधियों, कक्षाओं, चर, आदि के लिए कोई प्रतिस्थापन नहीं हैं, लेकिन कभी-कभी यह कहते हुए कि कुछ ऐसा क्यों है जो गरीब बेवकूफ के लिए बेहद मूल्यवान हो सकता है, जिसे कोड बनाए रखना होगा छह महीने में - विशेष रूप से उस गरीब बेवकूफ हवाओं आप जा रहा है।
मैं जिस कोड पर काम कर रहा हूं, उससे कुछ वास्तविक टिप्पणियां:
// 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.
आदर्श रूप से, कोड को इतनी अच्छी तरह से कोडित किया जाना चाहिए कि यह ऑटो एक्सप्लोसिव होना चाहिए। वास्तविक दुनिया में, हम जानते हैं कि कभी-कभी टिप्पणी करने के लिए बहुत उच्च गुणवत्ता वाले कोड की भी आवश्यकता होती है।
आपको पूरी तरह से बचना चाहिए "टिप्पणी-कोड अतिरेक" (टिप्पणियाँ जो कोड में कुछ भी नहीं जोड़ता है):
i++; // Increment i by 1
फिर, यदि एक अच्छा (और अनुरक्षित / संरेखित) कोड डिज़ाइन और प्रलेखन है, तो टिप्पणी करना और भी कम उपयोगी है।
लेकिन कुछ परिस्थितियों में टिप्पणी कोड पठनीयता में एक अच्छी सहायता हो सकती है:
while( foo )
{
if( dummy )
{
}
else // !dummy
{
}
} // end while( foo )
मत भूलो कि आपको बनाए रखना है और सिंक में भी रखना है टिप्पणी ... पुरानी या गलत टिप्पणियाँ एक भयानक दर्द हो सकती हैं! और, एक सामान्य नियम के रूप में, बहुत अधिक टिप्पणी करना खराब प्रोग्रामिंग का लक्षण हो सकता है।
} //end while
बस इसका मतलब है कि लूप की शुरुआत इतनी दूर है, आप इसे देख भी नहीं सकते हैं, और कोई संकेत नहीं हैं कि जिस कोड को आप देख रहे हैं वह लूप में है। कोड को संरचित करने के तरीके के बारे में टिप्पणियों के लिए भारी रिफैक्टिंग को गंभीरता से पसंद किया जाना चाहिए।
} // end while
टिप्पणियां जीवनरक्षक हो सकती हैं।
स्पष्ट रूप से "कोड गंध" के रूप में एक विधि या प्रक्रिया को परिभाषित करना एक "ज़ीलोट्री गंध" है। यह शब्द नया "हानिकारक माना" बन रहा है।
कृपया याद रखें कि इन सभी प्रकार की चीजों को दिशानिर्देश माना जाता है।
अन्य जवाबों में से कई अच्छी सलाह देते हैं जब टिप्पणियों को वारंट किया जाता है।
व्यक्तिगत रूप से मैं बहुत कम टिप्पणियों का उपयोग करता हूं। गैर-स्पष्ट प्रक्रियाओं के उद्देश्य की व्याख्या करें और किसी को भी कभी-कभार होने वाली मृत्यु-खतरे को छोड़ दें, जो अपने आप में चीजों को बदलने के बारे में विचार कर सकता है जो कि सप्ताह के ट्यूनिंग की आवश्यकता होती है।
जब तक किंडरगार्टनर समझ सकता है, तब तक सब कुछ दर्शाते हुए यह संभवत: आपके समय का एक कुशल उपयोग नहीं है, और शायद यह और अधिक संक्षिप्त संस्करण का प्रदर्शन नहीं करेगा।
टिप्पणियां रन टाइम को प्रभावित नहीं करती हैं, इसलिए विचार करने के लिए केवल नकारात्मक मुद्दा रखरखाव है।
कुछ मामलों में, अच्छा नामकरण, रीफैक्टरिंग आदि की कोई राशि टिप्पणी को प्रतिस्थापित नहीं कर सकती है। इस वास्तविक दुनिया के उदाहरण को देखें (भाषा ग्रूवी है):
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
यहां प्राथमिक मुद्दा "कोड गंध" शब्द का अर्थ है।
बहुत से लोग (आपके सहित, मुझे लगता है) एक कोड गंध को एक त्रुटि के करीब होने के लिए या कम से कम कुछ ऐसी चीज़ों को समझता है जिसे ठीक करने की आवश्यकता है। शायद आप इसे "एंटी-पैटर्न" का पर्याय मानते हैं।
यह शब्द का अर्थ नहीं है!
कोड गंध रूपक वार्ड विकी से निकलता है , और वे तनाव देते हैं:
ध्यान दें कि एक CodeSmell एक संकेत है कि कुछ गलत हो सकता है, निश्चितता नहीं। एक पूरी तरह से अच्छी मुहावरे को कोडस्मेल माना जा सकता है क्योंकि इसका अक्सर दुरुपयोग होता है, या क्योंकि एक सरल विकल्प है जो ज्यादातर मामलों में काम करता है। किसी कोडस्मेल को कुछ कॉल करना एक हमला नहीं है; यह बस एक संकेत है कि एक करीब देखो वारंट है।
तो इसका क्या मतलब है कि टिप्पणियां एक कोड-गंध हैं: इसका मतलब है कि जब आप एक टिप्पणी देखते हैं, तो आपको रोकना चाहिए और सोचना चाहिए: "हम्म, मुझे एक संकेत है कि कुछ सुधार किया जा सकता है"। शायद आप एक चर का नाम बदल सकते हैं, "एक्स्ट्रेक्ट मेथड" कर सकते हैं -सक्रियता - या शायद टिप्पणी वास्तव में सबसे अच्छा समाधान है।
संपादित करें: मैं सिर्फ इन दो लेखों पर स्तब्ध हूं, जो इसे मुझसे बेहतर बताते हैं:
मुझे लगता है कि नियम काफी सरल है: अपने कोड को देखकर एक पूर्ण अजनबी की कल्पना करें। आप शायद 5 वर्षों में अपने स्वयं के कोड के लिए एक अजनबी होंगे। इस अजनबी के लिए अपने कोड को समझने के लिए मानसिक प्रयास को कम करने की कोशिश करें।
सही टिप्पणी करने के लिए एक अच्छा विचार टिप्पणियों को लिखने के साथ शुरू करना है।
// 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 ...
उन चीजों के लिए जिन्हें अलग नहीं किया जा सकता है केवल तरीके न निकालें और टिप्पणी के तहत कोड लिखें।
यह वही है जो मैं एक न्यूनतम के लिए टिप्पणी करने के लिए एक उपयोगी तरीके के रूप में देखता हूं, प्रत्येक पंक्ति पर टिप्पणी करने के लिए वास्तव में बेकार है ... केवल एक पंक्ति का दस्तावेज़ यदि यह एक जादू मूल्य आरंभीकरण के बारे में है या जहां यह समझ में आता है।
यदि मापदंडों का बहुत अधिक उपयोग किया जाता है, तो वे आपकी कक्षा में निजी सदस्य होने चाहिए।
मुझे लगता है कि उत्तर सामान्य है "यह निर्भर करता है" एक। कोड को केवल टिप्पणी कोड कहना एक गंध है। टिप्पणी कोड क्योंकि आप एक अस्पष्ट एल्गोरिथ्म का उपयोग कर रहे हैं जो कि परिमाण का एक क्रम है तेजी से रखरखाव प्रोग्रामर को बचाता है (आमतौर पर मुझे इसे लिखने के 6 महीने बाद) कोड के माध्यम से प्रहार करने का आधा दिन यह निर्धारित करने के लिए कि यह क्या कर रहा है।
// Dear me in the future. Please, resolve this problem.
या
// You think this code was written by somebody else.
// No, it wasn't. You ([some name]) did it.
कोड टिप्पणियां निश्चित रूप से "कोड गंध" नहीं हैं। यह विश्वास आम तौर पर इस तथ्य से आता है कि टिप्पणी बासी (पुरानी) हो सकती है और इसे बनाए रखना मुश्किल हो सकता है। हालाँकि, अच्छी टिप्पणियाँ होने के कारण जो यह बताती है कि कोड कुछ निश्चित तरीके से (और आमतौर पर) रखरखाव के लिए महत्वपूर्ण है।
अच्छी टिप्पणियों से यह समझना आसान हो जाता है कि कोड क्या कर रहा है और, अधिक महत्वपूर्ण, यह एक विशेष तरीके से क्यों कर रहा है। टिप्पणियाँ प्रोग्रामर्स द्वारा पढ़ी जानी हैं और स्पष्ट और सटीक होनी चाहिए। एक टिप्पणी जो समझना मुश्किल है या गलत है, उस पर टिप्पणी करने से बेहतर नहीं है।
अपने कोड में स्पष्ट और सटीक टिप्पणियां जोड़ने का मतलब है कि आपको कोड के एक भाग के "क्या" और "क्यों" को समझने के लिए मेमोरी पर भरोसा करने की आवश्यकता नहीं है। यह सबसे महत्वपूर्ण है जब आप उस कोड को बाद में देखते हैं, या किसी और को आपके कोड को देखना चाहिए। क्योंकि टिप्पणियाँ आपके कोड की पाठ्य सामग्री का हिस्सा बन जाती हैं, उन्हें स्पष्ट रूप से लिखे जाने के अलावा अच्छे लेखन सिद्धांतों का पालन करना चाहिए।
एक अच्छी टिप्पणी लिखने के लिए, आपको कोड के उद्देश्य (क्यों, कैसे नहीं) का दस्तावेजीकरण करने की पूरी कोशिश करनी चाहिए और कोड के पीछे तर्क और तर्क को यथासंभव स्पष्ट रूप से इंगित करना चाहिए। आदर्श रूप से, टिप्पणियों को उसी समय लिखा जाना चाहिए जब आप कोड लिखते हैं। यदि आप प्रतीक्षा करते हैं, तो आप शायद वापस नहीं जाएंगे और उन्हें जोड़ देंगे।
सैम्स टी योरसेल्फ विज़ुअल सी # 2010 में 24 घंटे , पीपी 348-349।
यदि किसी पुस्तकालय में मौजूद समस्या से बचने के लिए एक विशेष तरीके से कोड लिखा गया है (दोनों एक तीसरे पक्ष के पुस्तकालय, या एक पुस्तकालय जो संकलक के साथ आता है), तो यह टिप्पणी करने के लिए समझ में आता है।
उदाहरण के लिए, कोड के बारे में भी समझ में आता है, जिसे भविष्य के संस्करणों में बदलने की आवश्यकता होती है, या लाइब्रेरी के नए संस्करण का उपयोग करते समय, या PHP4 से PHP5 में जाने पर।
यहां तक कि सबसे अच्छी तरह से लिखी गई पुस्तक में अभी भी एक परिचय और अध्याय शीर्षक है। अच्छी तरह से प्रलेखित कोड में टिप्पणियां अभी भी उच्च-स्तरीय अवधारणाओं का वर्णन करने के लिए उपयोगी हैं, और समझाती हैं कि कोड कैसे व्यवस्थित किया गया है।
मैं इस विचार से असहमत हूं कि कोड को समझाने के लिए टिप्पणियां लिखना बुरा है। यह पूरी तरह से इस तथ्य की अनदेखी करता है कि कोड में कीड़े हैं। यह स्पष्ट हो सकता है कि कोड टिप्पणियों के बिना क्या करता है । यह स्पष्ट होने की संभावना कम है कि कोड क्या करना चाहिए । टिप्पणियों के बिना आपको कैसे पता चलेगा कि परिणाम गलत हैं, या उनका गलत तरीके से उपयोग किया जा रहा है?
टिप्पणियों को कोड के इरादे को स्पष्ट करना चाहिए , ताकि अगर कोई गलती हो, तो टिप्पणियों को पढ़ने वाले + कोड को खोजने का एक मौका होता है।
कोड लिखने से पहले मैं आमतौर पर खुद को इनलाइन टिप्पणियां लिखता हूं। इस तरह यह स्पष्ट है कि मैं क्या करने के लिए कोड लिखने की कोशिश कर रहा हूं, और एल्गोरिथ्म में खो जाने को कम करता है बिना वास्तव में यह जानने के कि आप क्या करने की कोशिश कर रहे हैं।
टिप्पणियाँ जो किसी में डाल दी जाती हैं क्योंकि किसी को लगता है कि एक विधि में 700 लाइनें होना ठीक है।
टिप्पणियाँ जो वहाँ हैं क्योंकि आप जानते हैं कि यदि आप एक टिप्पणी में नहीं डालते हैं, तो कोई एक ही गलती करेगा फिर भी एक गंध है।
टिप्पणियाँ डाल दी क्योंकि कुछ कोड विश्लेषण उपकरण की मांग है कि यह भी एक गंध है।
जो लोग कभी टिप्पणी नहीं करेंगे , या अन्य डेवलपर्स के लिए थोड़ी मदद भी लिखेंगे, वह भी एक गंध है। मैं हैरान हूं कि कितने लोग नीचे सामान नहीं लिखेंगे, लेकिन फिर चारों ओर घूमेंगे और स्वीकार करेंगे कि वे याद नहीं कर सकते कि उन्होंने 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
आपको कोड और टिप्पणियों के बीच एक संतुलन रखना होगा ... आमतौर पर मैं कुछ टिप्पणियों को जोड़ने की कोशिश करता हूं जो कोड के ब्लॉक को फिर से शुरू करते हैं। इसलिए नहीं कि मैं कोड (अच्छी तरह से, वह भी) समझ नहीं पाऊंगा, बल्कि इसलिए कि मैं अपने कोड को तेजी से पढ़ सकता हूं और उन विशिष्ट खंडों का पता लगा सकता हूं जहां यह महत्वपूर्ण सामान हो रहा है।
वैसे भी, मेरा अपना व्यक्तिगत मानदंड है "जब संदेह, टिप्पणी"। मैं एक पूरी तरह से गुप्त रेखा की तुलना में एक निरर्थक रेखा रखना पसंद करता हूं जिसे मैं समझने में सक्षम नहीं हूं। मैं हमेशा एक कोड समीक्षा पर टिप्पणी निकाल सकता हूं, थोड़ी देर बाद (और मैं आमतौर पर करता हूं)
इसके अलावा, टिप्पणियां "कैविट्स" को जोड़ने में काफी मददगार हैं जैसे "सावधान रहें! यदि इनपुट का प्रारूप ASCII नहीं है, तो इस कोड को बदलना होगा!"
मुझे लगता है कि कोड कमेंट करने से जीवन की शुरुआत बहुत खराब हो जाती है। मैं इन दिनों के बारे में नहीं जानता, लेकिन जब मुझे पहली बार स्कूल में प्रोग्रामिंग सिखाई जा रही थी तो मुझे "एक प्रोग्राम लिखो जो अलग-अलग लाइनों पर एक से दस तक नंबर प्रिंट करता है। सुनिश्चित करें कि आप अपना कोड कमेंट करते हैं।" यदि आप टिप्पणी नहीं जोड़ते हैं तो आप नीचे सूचीबद्ध हो जाएंगे क्योंकि आपका कोड टिप्पणी करना एक अच्छा काम है।
लेकिन ऐसी तुच्छ प्रक्रिया के बारे में क्या कहना है? तो आप अंत में क्लासिक लिख रहे हैं
i++; // add one to the "i" counter.
बस एक सभ्य ग्रेड पाने के लिए और, यदि आप किसी भी तरह से किसी भी तरह के घोंसले के शिकार हैं, तो तुरंत कोड टिप्पणियों का एक बहुत ही कम राय बनाना।
कोड टिप्पणी एक अच्छी बात नहीं है। यह SOMETIMES NECESSARY THING है, और शीर्ष उत्तर में थॉमस ओवेन्स उन स्थितियों का उत्कृष्ट विवरण प्रदान करता है जिनमें यह आवश्यक है। हालांकि, ये स्थितियां शायद ही कभी होमवर्क-प्रकार के असाइनमेंट में फसल होती हैं।
कई मायनों में, एक टिप्पणी को जोड़ना एक अंतिम विकल्प माना जाना चाहिए, जब जो कहा जाना चाहिए वह प्रोग्रामिंग भाषा के सक्रिय भागों में स्पष्ट रूप से नहीं कहा जा सकता है। हालांकि ऑब्जेक्ट नामकरण बासी जा सकता है, विभिन्न मानव और कंप्यूटर की कमी-प्रतिक्रिया तंत्रों ने टिप्पणियों को बनाए रखना भूलना आसान बना दिया है और परिणामस्वरूप टिप्पणियां सक्रिय कोड की तुलना में बहुत अधिक तेजी से बासी हो जाती हैं। उस कारण से, जहां एक विकल्प संभव है, उसे स्पष्ट करने के लिए कोड बदलना हमेशा टिप्पणियों के साथ अस्पष्ट कोड की व्याख्या करने के लिए पसंद किया जाना चाहिए।
हर प्रोग्रामर जानता है कि हम सभी अंत में पागल बारी काम, डिबगिंग, या सिर्फ सादा पागलपन की मात्रा हम में चलाने की वजह से।
"यह करो!" आपके प्रोजेक्ट मैनेजर का कहना है
आप जवाब देते हैं, "यह नहीं किया जा सकता है।"
वे कहते हैं, "फिर हम इसे करने के लिए किसी और को खोज लेंगे।"
आप कहते हैं, "ठीक है, शायद यह किया जा सकता है।"
और फिर अगले दिनों की एक्स संख्या .. सप्ताह .. महीने .. इसे जानने का प्रयास करें। इस प्रक्रिया के दौरान, आप कोशिश करेंगे और असफल रहेंगे, और कोशिश करेंगे और असफल रहेंगे। हम सब यही करते हैं। सही उत्तर दो प्रकार के प्रोग्रामर हैं, जो टिप्पणी करते हैं और जो नहीं करते हैं।
1) जो लोग या तो भविष्य के संदर्भ के लिए दस्तावेज करके अपना काम आसान कर रहे हैं, असफल दिनचर्या पर टिप्पणी करते हैं जो काम नहीं करते थे (जो काम करता है उसे खोजने के बाद गंध उन्हें हटा नहीं रही है।), या टिप्पणी के साथ कोड को तोड़ना। उम्मीद करने के लिए स्वरूपण यह पढ़ने या समझने के लिए थोड़ा आसान बना देता है। सच में, मैं उन्हें दोष नहीं दे सकता। लेकिन अंत में, वे स्नैप करते हैं और फिर आपके पास यह है:
// dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2) वे जो या तो सुपर हीरो बनने का नाटक नहीं कर रहे हैं, या एक गुफा में रह रहे हैं । वे बस दूसरों के लिए लापरवाह उपेक्षा करते हैं, स्वयं, और कोड के बारे में कम परवाह कर सकते हैं, या बाद में इसका क्या अर्थ हो सकता है।
अब मुझे गलत मत समझो .. स्व-दस्तावेजीकरण चर और कार्य इससे पूरी तरह से बच सकते हैं .. और मुझे विश्वास है कि आप कभी भी पर्याप्त कोड-सफाई नहीं कर सकते। लेकिन सरल सच यह है कि जब तक आप बैकअप रखते हैं, आप हमेशा टिप्पणियों को हटा सकते हैं ।
मेरा तर्क है कि आपके कोड में कुछ टिप्पणियों का उपयोग नहीं करना एक कोड गंध है। जबकि मैं मानता हूं कि कोड को स्व-दस्तावेजीकरण जितना संभव हो उतना होना चाहिए, आपने एक निश्चित बिंदु मारा जहां आप कोड को देखने जा रहे हैं जो इस बात की परवाह किए बिना कि कोड कितना अच्छा लिखा गया है। मैंने व्यावसायिक अनुप्रयोगों में कुछ कोड देखे हैं जहाँ टिप्पणियाँ बहुत अनिवार्य हैं क्योंकि:
इसके अलावा, कंपनी की स्टाइल गाइड आपको कुछ निश्चित तरीके से करने के लिए कह सकती है - अगर वे कहते हैं कि आपकी टिप्पणी में यह टिप्पणी हो सकती है कि किसी फ़ंक्शन में कोड के ब्लॉक क्या कर रहे हैं, तो टिप्पणी शामिल करें।
टिप्पणियों और कोड के बीच एक बड़ा बुनियादी अंतर है: टिप्पणियां लोगों को अन्य लोगों के लिए विचारों को संवाद करने का एक तरीका है, जबकि कोड मुख्य रूप से कंप्यूटर के लिए है। "कोड" में कई पहलू हैं जो केवल मनुष्यों के लिए हैं, जैसे नामकरण और इंडेंटेशन। लेकिन टिप्पणियों को मनुष्यों द्वारा, मनुष्यों के लिए सख्ती से लिखा जाता है।
इसलिए, टिप्पणी लिखना किसी भी लिखित मानव संचार के रूप में हर बिट मुश्किल है! लेखक को एक स्पष्ट गर्भाधान होना चाहिए कि दर्शक कौन है, और उन्हें किस तरह के पाठ की आवश्यकता होगी। आप कैसे जान सकते हैं कि आपकी टिप्पणियाँ दस, बीस वर्षों में कौन पढ़ेगा? यदि व्यक्ति पूरी तरह से अलग संस्कृति से है तो क्या होगा? आदि मुझे आशा है कि हर कोई इसे समझता है।
यहां तक कि मैं जिस छोटी सी सजातीय संस्कृति में रहता हूं, उसके अंदर अन्य लोगों के लिए विचारों का संचार करना इतना मुश्किल है। दुर्घटना के अलावा, मानव संचार आमतौर पर विफल रहता है।
मुझे आपके सहकर्मी से सहमत होना होगा। मैं हमेशा कहता हूं कि अगर मैं अपना कोड कमेंट करता हूं, तो इसका मतलब है कि मुझे चिंता है कि मैं भविष्य में अपना कोड पता नहीं लगा पाऊंगा । यह एक बुरा संकेत है।
कोड में टिप्पणी छिड़कने का एकमात्र अन्य कारण कुछ ऐसा है जिसे समझ में नहीं आता है।
वे टिप्पणियाँ आमतौर पर कुछ इस तरह का रूप लेती हैं:
//xxx what the heck is this doing??
या
// removed in version 2.0, but back for 2.1, now I'm taking out again
कोड टिप्पणी, जहां लागू हो, फ़ंक्शन तर्कों और रिटर्न की संरचना, संरचना क्षेत्र, यहां तक कि स्थानीय चर भी बहुत आसान हो सकते हैं। मार्स ऑर्बिटर याद रखें!
साक्षर प्रोग्रामिंग तकनीक के बारे में अपने सहकर्मी को शिक्षित करें ।
नहीं, टिप्पणियां कोड गंध नहीं हैं, वे सिर्फ एक उपकरण हैं जिसका दुरुपयोग किया जा सकता है।
अच्छी टिप्पणियों के उदाहरण :
// मुझे लगता है कि यह सेमी में है। आगे की जांच की जरूरत है!
// यह एक्स करने का एक चतुर तरीका है
// सूची यहां गैर-रिक्त होने की गारंटी है
Assert(list.IsEmpty)
?
Assert(!list.isEmpty())
तीसरी टिप्पणी के रूप में वास्तव में एक अनुबंध नहीं है, लेकिन केवल व्यवहार (यानी "तर्क अवैध है, तो तर्क खाली होने पर फेंक दें") जो किसी भी अन्य प्रोग्राम लॉजिक की तरह यूनिट-परीक्षण किया जाना चाहिए। टिप्पणी के साथ सूक्ष्म अंतर पर ध्यान दें, जो बताता है कि विधि का उपयोग कब किया जा सकता है, लेकिन पूर्व व्यवहार पूरा नहीं होने पर कोई व्यवहार निर्दिष्ट नहीं करता है। टिप्पणी से बेहतर यह भी होगा कि संकलन-समय अनुबंधों को लागू किया जाए। लेकिन यह मेरे उत्तर के दायरे को
Assert
एस व्यायाम करने में सक्षम नहीं होना चाहिए , क्योंकि वे उन चीजों का वर्णन करते हैं जो कभी भी नहीं होना चाहिए, भले ही सार्वजनिक एपीआई को अमान्य तर्क मिले।