रॉबर्ट सी। मार्टिन उद्धरण को संदर्भ से बाहर ले जाया जाता है। यहाँ थोड़ा और अधिक संदर्भ के साथ उद्धरण है:
कुछ भी नहीं एक बहुत अच्छी तरह से टिप्पणी के रूप में उपयोगी हो सकता है। भद्दे डॉगमैटिक कमेंट्स से ज्यादा किसी मॉड्यूल को बंद नहीं कर सकते। झूठ और गलत सूचना का प्रचार करने वाले एक पुराने क्रुफ़्टी टिप्पणी के रूप में कुछ भी इतना हानिकारक नहीं हो सकता है।
टिप्पणियां शिंडलर्स लिस्ट की तरह नहीं हैं। वे "शुद्ध अच्छे नहीं हैं।" वास्तव में, टिप्पणियाँ, सबसे अच्छा, एक आवश्यक बुराई हैं। यदि हमारी प्रोग्रामिंग भाषाएं पर्याप्त रूप से अभिव्यक्त होती हैं, या यदि हमारे पास अपनी मंशा व्यक्त करने के लिए उन भाषाओं को सूक्ष्मता से लिखने की प्रतिभा है, तो हमें टिप्पणियों की बहुत आवश्यकता नहीं होगी - शायद बिल्कुल भी नहीं।
टिप्पणियों का उचित उपयोग कोड में खुद को व्यक्त करने में हमारी विफलता के लिए क्षतिपूर्ति करना है। ध्यान दें कि मैंने विफलता शब्द का उपयोग किया है। मैं दिल से ऐसा चाहता था। टिप्पणियाँ हमेशा विफल होती हैं। हमें उनके पास होना चाहिए क्योंकि हम हमेशा उनके बिना खुद को व्यक्त करने का पता नहीं लगा सकते हैं, लेकिन उनका उपयोग उत्सव का कारण नहीं है।
इसलिए जब आप खुद को एक ऐसी स्थिति में पाते हैं जहाँ आपको एक टिप्पणी लिखने की आवश्यकता होती है, तो इसके माध्यम से सोचें और देखें कि क्या टेबल को चालू करने और कोड में खुद को व्यक्त करने का कोई तरीका नहीं है। हर बार जब आप खुद को कोड में व्यक्त करते हैं, तो आपको खुद को पीठ पर थपथपाना चाहिए। हर बार जब आप एक टिप्पणी लिखते हैं, तो आपको अपनी अभिव्यक्ति की क्षमता की विफलता को महसूस करना चाहिए।
( यहां से नकल की गई , लेकिन मूल उद्धरण क्लीन कोड से है: ए हैंडबुक ऑफ एजाइल सॉफ्टवेयर क्राफ्ट्समैनशिप )
इस उद्धरण को "टिप्पणियों में हमेशा विफलताएं" कैसे कम किया जाता है, इस बात का एक अच्छा उदाहरण है कि कैसे कुछ लोग संदर्भ से बाहर एक समझदार उद्धरण लेंगे और इसे बेवकूफ हठधर्मिता में बदल देंगे।
एपीआई प्रलेखन (जेवाडॉक की तरह) एपीआई का दस्तावेज माना जाता है, ताकि उपयोगकर्ता स्रोत कोड को पढ़ने के बिना इसका उपयोग कर सकें । तो इस मामले में प्रलेखन को यह बताना चाहिए कि विधि क्या करती है। अब आप तर्क दे सकते हैं कि "अपनी आईडी द्वारा एक उत्पाद को पुनर्प्राप्त करता है" बेमानी है क्योंकि यह पहले से ही विधि नाम से इंगित किया गया है, लेकिन जो जानकारी nullवापस आ सकती है वह निश्चित रूप से दस्तावेज़ के लिए महत्वपूर्ण है, क्योंकि यह किसी भी तरह से स्पष्ट नहीं है।
यदि आप टिप्पणी की आवश्यकता से बचना चाहते हैं, तो आपको nullएपीआई को और अधिक स्पष्ट करके अंतर्निहित समस्या को दूर करना होगा (जो कि वैध रिटर्न मूल्य के रूप में उपयोग होता है )। उदाहरण के लिए आप किसी प्रकार का रिटर्न दे सकते हैं Option<Product>, इसलिए टाइप सिग्नेचर स्वयं स्पष्ट रूप से संचार करता है कि उत्पाद नहीं मिला है या नहीं।
लेकिन किसी भी मामले में केवल विधि के नाम और प्रकार के हस्ताक्षर के माध्यम से पूरी तरह से एपीआई का दस्तावेजीकरण करना यथार्थवादी नहीं है। किसी भी अतिरिक्त गैर-स्पष्ट जानकारी के लिए डॉक्टर-टिप्पणियों का उपयोग करें, जो उपयोगकर्ता को जानना चाहिए। DateTime.AddMonths()बीसीएल में एपीआई प्रलेखन को कहें :
AddMonths विधि परिणामी महीने और वर्ष की गणना करती है, एक महीने में लीप वर्ष और दिनों की संख्या को ध्यान में रखते हुए, फिर परिणामी DateTime ऑब्जेक्ट के दिन भाग को समायोजित करती है। यदि परिणामी दिन परिणामी महीने में मान्य दिन नहीं है, तो परिणामी महीने के अंतिम वैध दिन का उपयोग किया जाता है। उदाहरण के लिए, 31 मार्च + 1 महीना = 30 अप्रैल। परिणामी DateTime ऑब्जेक्ट का दिन का समय इस उदाहरण के समान रहता है।
कोई तरीका नहीं है कि आप इसे केवल विधि नाम और हस्ताक्षर का उपयोग करके व्यक्त कर सकते हैं! बेशक आपके वर्ग के प्रलेखन को विस्तार के इस स्तर की आवश्यकता नहीं हो सकती है, यह सिर्फ एक उदाहरण है।
इनलाइन टिप्पणियां भी खराब नहीं हैं।
भद्दे कमेंट्स बुरे हैं। उदाहरण के लिए टिप्पणियाँ जो केवल बताती हैं कि कोड से तुच्छ रूप से क्या देखा जा सकता है, शास्त्रीय उदाहरण:
// increment x by one
x++;
टिप्पणियाँ, जो किसी चर या विधि का नाम बदलकर या अन्यथा कोड का पुनर्गठन करके स्पष्ट की जा सकती हैं, एक कोड गंध है:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
मार्टिन ने जिस तरह की टिप्पणी की, उसके खिलाफ ये हैं। टिप्पणी स्पष्ट कोड लिखने में विफलता का एक लक्षण है - इस मामले में चर और विधियों के लिए स्व-व्याख्यात्मक नामों का उपयोग करना। टिप्पणी स्वयं समस्या नहीं है, समस्या यह है कि हमें कोड को समझने के लिए टिप्पणी की आवश्यकता है।
लेकिन टिप्पणियों का उपयोग उन सभी चीजों को समझाने के लिए किया जाना चाहिए जो कोड से स्पष्ट नहीं हैं, जैसे कि कोड को एक निश्चित गैर-स्पष्ट तरीके से क्यों लिखा जाता है:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
टिप्पणियां जो बताती हैं कि कोड का एक अत्यधिक जटिल टुकड़ा क्या एक गंध भी है, लेकिन टिप्पणी टिप्पणियों को स्पष्ट नहीं करना है, फिक्स कोड को ठीक करना है! वास्तविक शब्द में, सजाया हुआ कोड होता है (उम्मीद है कि केवल अस्थायी रूप से एक रिफ्लेक्टर तक) लेकिन कोई भी सामान्य डेवलपर पहली बार सही स्वच्छ कोड नहीं लिखता है। जब आक्षेपित कोड होता है, तो एक टिप्पणी लिखना बेहतर होता है जो यह बताता है कि यह एक टिप्पणी नहीं लिखता है। इस टिप्पणी से बाद में रिफ्लेक्टर करना भी आसान हो जाएगा।
कभी-कभी कोड अपरिहार्य रूप से जटिल होता है। यह एक जटिल एल्गोरिथ्म हो सकता है, या यह प्रदर्शन कारणों से स्पष्टता का त्याग करने वाला कोड हो सकता है। फिर से टिप्पणी आवश्यक है।