कोड में टिप्पणियाँ - उपयोगी, अर्थहीन, हानिकारक?

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



इसलिए, मैं कुछ उत्तेजक बयान दूँगा, फिर उन्हें उदाहरणों के साथ वापस करने का प्रयास करेंगे। देखते हैं क्या होता है। यह कोड में दोनों (जावा) डॉक्टर और नियमित टिप्पणियों पर लागू होता है।



तो:





1. टिप्पणी उपयोगी, अर्थहीन या हानिकारक हो सकती है।

2. यदि टिप्पणी में स्पष्ट रूप से दिखाई देने वाले लाभ नहीं हैं, तो यह सबसे अधिक हानिकारक है।

3. टिप्पणियाँ बेकार / हानिकारक होती हैं जितनी बार वे लगती हैं। टिप्पणी की कमी बेकार टिप्पणी से बेहतर है।

4. इससे पहले कि आप एक टिप्पणी लिखें - दो बार सोचें, शायद इसके लायक नहीं है? :)

(5. आपके द्वारा यह तय करने के बाद कि टिप्पणी की अभी भी आवश्यकता नहीं है, तीन बार देखें - क्या कोड क्रिस्टल स्पष्ट है? :)



उपयोगी टिप्पणियों के बारे में, सब कुछ स्पष्ट है। जब:

- व्यापार तर्क के साथ विधि कोड के 80 लाइनों के बजाय सिर्फ 6 पंक्तियों की टिप्पणी पढ़ें

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

- टिप्पणी बताती है कि लेखक इस दृष्टिकोण का उपयोग क्यों नहीं करता है कि रीडिंग कोड सबसे अधिक संभावना है कि वह यहां देख सकता है (उदाहरण के लिए, ओआरएम फ्रेमवर्क के माध्यम से काम करने के बजाय एक हाथ से लिखी गई SQL क्वेरी, या एक्सपीथ के बजाय रीपेक्सपी का उपयोग एक्सएमएल में खोज के लिए क्यों किया जाता है)

- टिप्पणी में उपयोग का एक छोटा स्पष्ट उदाहरण दिया गया है (विशेषकर यदि यह किसी प्रकार का कस्टम चींटी कार्य या कुछ इसी तरह का है),



यह लगभग निश्चित रूप से एक उपयोगी और कभी-कभी आवश्यक टिप्पणी है।



अब आइए कुछ अन्य सामान्य उदाहरण देखें।

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

1. / **
2. * एंटरप्राइज़नाम वापस करें
3. * /
4. सार्वजनिक स्ट्रिंग getEnterpriseName () {
5. एंटरप्राइज नेम;
6. }

कमेंट्री की ज़रुरत नहीं है। कोड में कुछ भी नहीं है, टिप्पणी अनिवार्य रूप से कोड को डुप्लिकेट करती है। इसके अलावा, यहां टिप्पणी कोड संपादक में तीन लाइनें लेती है। यानी कोड जितना ही। न केवल कोड ही है, वास्तव में, सिंथेटिक, + ​​जावा कोड कन्वेंशनों के कारण, पठनीयता के लिए तीन लाइनें खिंची हुई हैं, इसलिए टिप्पणी भी अंतरिक्ष खाती है।

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



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



माना गया उदाहरण अक्सर इस तथ्य से बढ़ जाता है कि परम , रिटर्न टैग को टिप्पणी में धकेल दिया जाता है, जो अक्सर उपयोगी जानकारी नहीं रखते हैं, लेकिन वे जगह खाते हैं। उदाहरण के लिए:



/ **

*

* कुछ विवरण।

* परम parNName1 paramName1

* परम परमनाम २ परमनाम २

* परम परमनाम 3 परमनाम 3

* उपयोगकर्ता का नाम वापस करें

* /

सार्वजनिक स्ट्रिंग getUserName (स्ट्रिंग paramName1, int paramName2, int paramName2)

/ * कुछ सरल सीधे कोड * /

}



(यह हास्यास्पद है कि अक्सर कोड में ऐसी अर्थहीन टिप्पणियां होती हैं, लेकिन वास्तव में टिप्पणियों के जटिल हिस्सों में कुछ :) हैं



और अंत में, एक और उदाहरण।



// अस्थायी हैक, क्योंकि अब ठीक करने की क्षमता समर्थित नहीं है,

// लेकिन आपको इसे तत्काल करने की आवश्यकता है। [वरिष्ठ डेवलपर नाम] की सलाह पर, उन्होंने इस तरह हैक किया।

// 04/21/2004, [डेवलपर नाम]।



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



अपडेट किया गया:

टिप्पणियों के अनुरोध पर, मैं उन पुस्तकों की एक जोड़ी का लिंक देता हूं जो किसी भी प्रोग्रामर के लिए पढ़ने के लिए उपयोगी हैं ताकि इस तरह की टिप्पणियों को न लिखें (और कई अन्य गलतियां न करें)



स्टीव मैककोनेल। बिल्कुल सही कोड। www.ozon.ru/context/detail/id/5508646

मार्टिन फाउलर। पुनर्रचना। मौजूदा कोड में सुधार। www.ozon.ru/context/detail/id/4952415