मैंने jQuery कोड की टिप्पणियों से कई अंक संख्याएं देखीं । (वास्तव में, jQuery कोड में 69 इश्यू नंबर थे।) मुझे लगता है कि यह अच्छा अभ्यास होगा, लेकिन मैंने कभी कोई दिशानिर्देश नहीं देखा है।
यदि यह एक अच्छा अभ्यास है, तो इस अभ्यास के लिए क्या दिशा निर्देश हैं?
जवाबों:
सामान्य तौर पर, मैं इसे अच्छा अभ्यास नहीं मानूंगा। लेकिन असाधारण मामलों में, यह बहुत उपयोगी हो सकता है, अर्थात् जब किसी जटिल मुद्दे को ठीक करने के लिए कोड को कुछ अनपेक्षित करना पड़ता है, और किसी भी स्पष्टीकरण के बिना एक जोखिम होगा कि कोई इस अजीब कोड को "ठीक" करना चाहता है और इस तरह इसे तोड़ सकता है , जबकि तर्क के बारे में बताते हुए एक बड़ी टिप्पणी होगी जो इस मुद्दे की जानकारी को दोहराती है।
मुझे लगता है कि जब आप अपने स्रोत नियंत्रण प्रणाली से संबंधित सुधार करते हैं, तो प्रतिबद्ध नंबर को संदेश में जोड़ने के लिए पर्याप्त है।
उदाहरण के लिए:
बग # 203: डेटाबेस कनेक्शन 30 सेकंड के बाद बाहर समय नहीं देता है।
मुझे लगता है कि अंक संख्या, डेवलपर के नाम या तिथियों को जोड़ने से कोड में बदलाव किए गए हैं जो कोडबेस को प्रदूषित करते हैं और वास्तव में आपके स्रोत नियंत्रण प्रणाली द्वारा बाह्य रूप से प्रबंधित किए जाने चाहिए।
मैं यहाँ अन्य पोस्टरों से पूरी तरह असहमत हूँ!
ट्रैकिंग संदर्भ के साथ कोड टिप्पणियाँ रखरखाव प्रोग्रामिंग के लिए एक बड़ी मदद हो सकती हैं।
अगर मैं बग को ट्रैक कर रहा हूं और कोड के क्षेत्र के करीब पहुंच रहा हूं, तो यह देखने के लिए कि हाल ही में इसे बदल दिया गया है और परिवर्तन के संदर्भ में लिंक बंद है एक ईश्वर-भेजें।
हां, हमारे पास स्रोत कोड नियंत्रण है, लेकिन व्यक्तिगत रूप से फ़ाइलों और मॉड्यूल की जांच करना काफी धीमा हो सकता है। आप चाहते हैं कि ये चीजें हाल के बदलावों के लिए आप पर छाई रहें।
मैं शायद उन्हें अपदस्थ कर दूंगा क्योंकि मैं वास्तव में पुराने लोगों को कोड बेस में देखता हूं, लेकिन हाल ही में और अधिक संभावित रूप से सहेजे गए डेवलपर समय के बहुत कम रखने के पक्ष में है यदि आप उन्हें स्मार्ट तरीके से उपयोग करते हैं।
मुझे लगता है कि आपके बग ट्रैकिंग सिस्टम के ये छोटे संदर्भ कोड में विस्तृत टिप्पणियों के लिए बेहतर हैं।
git gui blame <filename>यदि आप git का उपयोग करते हैं तो कोड इतिहास ब्राउज़ करने के लिए डिफ़ॉल्ट बहुत तेज़ GUI प्रदान करता है। इतिहास के साथ कोड टिप्पणियों को संयोजित करने के लिए एक उपकरण का उपयोग करना कोड के लिए किसी भी इनलाइन टिप्पणियों की तुलना में बहुत बेहतर प्रलेखन की अनुमति देता है। यही है, यदि आप परेशान करते हैं तो अच्छा प्रतिबद्ध संदेश लिखें (एक अच्छा प्रतिबद्ध संदेश मोटे तौर पर एक ईमेल संदेश के बराबर होना चाहिए जो यह समझाता है कि क्यों पैच लागू किया जाना चाहिए)।
यदि आप "क्लीन कोड" की नीति की सदस्यता लेते हैं, तो आपको शायद खुद से पूछने की ज़रूरत है कि क्या टिप्पणियों को जोड़ना अच्छा है। यदि कोड को केवल एक टिप्पणी के साथ स्पष्ट किया जा सकता है, तो सुनिश्चित करें, एक जोड़ें, अन्यथा आपको आसानी से यह समझने में सक्षम होना चाहिए कि आपका कोड इसे पढ़कर क्या करता है (बशर्ते आप अपने चर, विधियों, आदि के लिए समझदार नामों का उपयोग कर रहे हों)।
इस बारे में आपकी व्यक्तिगत राय कि टिप्पणी करना अच्छा व्यवहार है या नहीं, एक टिप्पणी में ऐसी जानकारी होनी चाहिए जो उस कोड के प्रत्यक्ष मूल्य का हो जो टिप्पणी का संदर्भ दे रहा है। इस मामले में, सवाल यह है कि क्या अंक संख्या जोड़ने से कोड में मूल्य जुड़ जाता है। समस्या मैं समस्या संख्या को जोड़ने के साथ देख रहा हूं कि आपके पास कई मुद्दों को संतुष्ट करने के लिए कोड का एक खंड हो सकता है, जिसे भारी रूप से संशोधित किया जा सकता है, और थोड़ी देर के बाद, किसी विशिष्ट मुद्दे से संबंधित परिवर्तनों को सही ढंग से पहचानना असंभव हो सकता है। उदाहरण के लिए बाद के मुद्दों को पूर्व में जारी मुद्दों से संबंधित कोड की आवश्यकता हो सकती है जो कि भारी रिफ्लेक्ट किए जाएं। यह शायद एक चरम उदाहरण है, हालांकि यह दिखाता है कि कोड में टिप्पणियों में समस्या संख्याएं कितनी बेकार हो सकती हैं।
यदि आप इस बात की गारंटी दे सकते हैं कि जिस स्थिति का मैंने अभी वर्णन किया है वह कभी नहीं होगा, मैं अभी भी यह तर्क दूंगा कि समस्या के बारे में क्या है, और फिर भी, इस जानकारी के सभी वास्तव में आपके हैं ट्रैकिंग सिस्टम जारी करें और इसे डुप्लिकेट किया जाना चाहिए। समस्या नंबर नोट करने के लिए एक बेहतर जगह आपके संस्करण नियंत्रण प्रणाली में एक टिप्पणी के रूप में होगी। लाभ यह है कि आप संस्करणों की तुलना कर सकते हैं और किसी विशिष्ट मुद्दे से संबंधित कोड परिवर्तन देख सकते हैं, जबकि समस्या नंबर आपको आवश्यक पहचानकर्ता प्रदान करता है यदि आप कोड में बदलाव के कारण की समीक्षा करना चाहते हैं।
इस सब को ध्यान में रखते हुए, मेरा सुझाव है कि यह वास्तव में अच्छा नहीं है क्योंकि आपके कोड में टिप्पणियों में इस तरह की संख्याओं को जोड़ना है।
मुझे लगता है कि टिप्पणी में संक्षिप्त विवरण देते हुए, आगे पढ़ने के लिए एक मुद्दे का उल्लेख करना अच्छा है।
मैं आमतौर पर केवल टिप्पणियों को जोड़ता हूं यदि कोड के उस टुकड़े में कुछ सूक्ष्म या अनपेक्षित है। चूँकि कुछ सूक्ष्म मुद्दों को पूरी तरह से कुछ पंक्तियों में नहीं समझाया जा सकता है, और मैं दर्जनों लाइनों की टिप्पणियों को जोड़ना नहीं चाहता हूँ, मैं एक छोटी टिप्पणी जोड़ूंगा जो यह बताएगी कि यह क्या हासिल करने की कोशिश कर रहा है, और इस मुद्दे को देखें विवरण।
उदाहरण के लिए:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
जहाँ मुद्दा 123 में बताया गया है कि यह हमला कैसा लग सकता है, और हमले के लिए नया कोड प्रतिरक्षा क्यों है।
या:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
अपने स्रोत में अंक संख्या डालने के साथ मुख्य समस्या यह है कि अब आपके पास एक बाहरी संदर्भ है। इसलिए आपको यह सुनिश्चित करने की आवश्यकता है कि आप इस मुद्दे को नहीं खोएंगे।
जब आपके स्रोत कोड को निरंतर एकीकरण के साथ वायर्ड किया जाता है, तो प्रतिबद्ध संदेशों में समस्या संख्या शामिल करना बहुत उपयोगी हो सकता है। TeamCity जैसे एप्लिकेशन उस सूचना को बाहर निकालेंगे और बेहतर रिपोर्टिंग की अनुमति देंगे।
उपरोक्त के साथ मैंने कहा कि मैं 100% निश्चित नहीं हूं कि यह कोड टिप्पणियों से खींचता है। यदि कोड संख्याएँ बनी रहती हैं (जैसे आप समस्या ट्रैकर नहीं बदलते हैं) तो कोड में अंक संख्याएँ अच्छी तरह से काम करती हैं और आपके पास दिए गए प्रोजेक्ट के लिए बहुत सारे मुद्दे नहीं हैं।
यह संभवतः अधिक उपयोगी है यदि आप समस्या और समाधान का वर्णन करते हैं तो अगले डेवलपर को अंक संख्या देखने की आवश्यकता नहीं है। कंपाइलर या मिनिफ़ायर कोड में जारी होने से पहले आपकी टिप्पणियों को हटा देगा, ताकि अंतिम परिणाम पर कोई प्रभाव न पड़े।