कोड रखरखाव: कोड में टिप्पणी जोड़ने के लिए या केवल संस्करण नियंत्रण के लिए इसे छोड़ दें?

Question

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

मेरी चिंता यह है कि क्या यह कोई अतिरिक्त मूल्य प्रदान करता है? जैसा कि यह है, हमारे पास संस्करण नियंत्रण इतिहास में सभी विवरण हैं, जो हमें प्रत्येक परिवर्तन को ट्रैक करने में मदद करेंगे?

लेकिन मेरे लीड्स कमेंट्स को एक "अच्छी" प्रोग्रामिंग प्रैक्टिस की तरह समझ रहे हैं। उनका एक तर्क यह है कि जब एक सीआर को डी-स्कॉप्ड / चेंज किया जाना होता है, तो यह बोझिल होगा यदि टिप्पणियां नहीं हैं।

यह देखते हुए कि परिवर्तन बड़े पैमाने पर कोड के बीच में होंगे, क्या यह वास्तव में हमारे द्वारा किए गए प्रत्येक परिवर्तन के लिए टिप्पणियां जोड़ने में मदद करेगा? क्या हमें इसे संस्करण नियंत्रण पर नहीं छोड़ना चाहिए?

Answer 1

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

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

हर बार जब आप बग को ठीक करते हैं, तो आप जल्दी से अपने कोड को बिना पढ़े और अनमने कर सकते हैं। यह दो स्थानों पर एक ही जानकारी को डुप्लिकेट करने का परिणाम देगा, जिससे गड़बड़ और भी खराब हो जाएगी।

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

इसलिए इसके बजाय

// fixed bug XXXXX on 10/9/2012

आपके पास एक टिप्पणी हो सकती है जो कहती है

// doing X, because otherwise Y will break.

या

// doing X, because doing Y is 10 times slower.

Comments

टिप्पणियों की कोड गंध के लिए +1 जो "क्या" समझाते हैं। यह प्रतिक्रिया देखकर अच्छा लगता है कि कोड टिप्पणियां इस मायने में स्वचालित लाभ नहीं हैं कि अधिक टिप्पणियां> कम टिप्पणियां। मैं एक स्तर भी पीछे खींच सकता हूं और सोचता हूं कि ऐसे मामले भी हैं जहां "क्यों" टिप्पणी का वर्णन करते हुए भी यह संकेत मिलता है कि कोड स्पष्ट नहीं है। उदाहरण के लिए, यदि मैं किसी बबलसॉर्टर या क्विकसोर्टर को इंजेक्ट कर सकता हूं, तो टिप्पणी "मैं क्विकसोर्टर का उपयोग कर रहा हूं क्योंकि यह तेज है" उसी तरह से शानदार है जैसे कि "एक क्विकसेलर को इंजेक्ट करें" शानदार है। YMMV।

— एरिक डिट्रिच 21

Answer 2

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

स्रोत कोड की पठनीयता सर्वोपरि है। एक कोडबेस जो हर बगफिक्स और सीआर द्वारा किए गए इतिहास को पूरा करने वाली टिप्पणियों के साथ जुड़ा हुआ है, बिल्कुल भी पढ़ने योग्य नहीं है।

लेकिन टिप्पणियों को पूरी तरह से न छोड़ें: अच्छी टिप्पणियां (प्रत्येक बगफिक्स और सीआर के हर प्रारंभ / स्टॉप / विवरण / समाधान का दस्तावेजीकरण नहीं) कोड की पठनीयता को बढ़ाता है। उदाहरण के लिए, एक बग को ठीक करने के लिए एक ट्रिकी या अस्पष्ट बिट के लिए, जिसे आप बग को ठीक करने के लिए जोड़ते हैं, जो यह // fix ISSUE#413बताता है कि आपके इश्यू ट्रैकर में अधिक जानकारी कहां से मिल सकती है, यह एक उत्कृष्ट विचार है।

Comments

मैं एक बात को छोड़कर सहमत हूं: fix ISSUE#413कोड में एक अच्छी टिप्पणी नहीं है। आपको बाहरी दस्तावेज को संदर्भित किए बिना कोड को समझने में सक्षम होना चाहिए। एक यादृच्छिक संख्या देने के बजाय, वास्तव में समझाएं कि कोड के इस पेचीदा हिस्से को क्या करना आवश्यक है। यह टिप्पणी किसके लिए है: कोड के उन हिस्सों की व्याख्या करना जो स्पष्ट नहीं हैं।

— प्रहार

@ पोक - इस ओर इशारा करने के लिए धन्यवाद। मुझे लगता है कि मुझे यह जोड़ना चाहिए कि मैं केवल उसी जगह का उपयोग करता हूं fix ISSUE#413जहां फ़ॉर्म की टिप्पणियों का उपयोग किया जाता है, जहां समस्या इतनी जटिल है (एक अत्यंत OS- और कॉन्फ़िगरेशन-निर्भर कोने का मामला है, या केवल विशेष खराब ग्राहक डेटा द्वारा ट्रिगर किया गया है) जो पर्याप्त रूप से वर्णन कर रहा है पैराग्राफ की जोड़ी; इस तरह की चीज़ को एक समस्या ट्रैकर, आईएमओ द्वारा बेहतर तरीके से नियंत्रित किया जाता है। फिर भी, किसी प्रकार का संक्षिप्त विवरण अच्छा है।

— जोश केली

@ प्रहार: मैं कहूंगा कि एक टिप्पणी जो शुरू होती है fix ISSUE#413 वह पूरी तरह से ठीक है, और यहां तक ​​कि बेहतर भी है, जब तक कि यह # 413 क्या समस्या है के बारे में उचित जानकारी प्रदान करता है। बस एक पॉइंटर प्रदान किए बिना मुद्दे की रिपोर्ट को संक्षेप में प्रस्तुत करना भविष्य के पाठक के लिए जीवन को अधिक कठिन बनाता है, जिसे सभी विवरणों की आवश्यकता होती है।

— कीथ थॉम्पसन

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

— माइकल डीन

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

— एंडी

Answer 3

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

वीसीएस में टिप्पणियाँ इस बारे में हैं कि कोड कैसे बदल गया है। उन्हें विकास की कहानी के रूप में पढ़ना चाहिए।

अब, हर बदलाव में टिप्पणियां शामिल होनी चाहिए? ज्यादातर मामलों में, हाँ। एकमात्र अपवाद जिसकी मैं कल्पना करता हूं, जब अपेक्षित व्यवहार पहले से ही प्रलेखित था, लेकिन बग के कारण आपको क्या नहीं मिला। इसे ठीक करने से मौजूदा टिप्पणियां अधिक सटीक हो जाती हैं, इसलिए उन्हें बदलना नहीं पड़ता है। बग को स्वयं टिकट इतिहास और प्रतिबद्ध टिप्पणी में प्रलेखित किया जाना चाहिए, लेकिन केवल कोड में अजीब लगने पर। उस मामले में, एक // make sure <bad thing> doesn't happenपर्याप्त होना चाहिए।

Comments

मैं इसे बढ़ा दूंगा, लेकिन मैं वास्तव में "हर बदलाव में टिप्पणियों को शामिल करना चाहिए? ज्यादातर मामलों में, हाँ" से सहमत नहीं हो सकता। एक चेक-इन / प्रतिबद्ध टिप्पणी, हाँ, बिल्कुल। कोड टिप्पणी, निश्चित रूप से जरूरी नहीं है।

— एक सीवीएन

Answer 4

एक प्रकार की टिप्पणी जिसकी मैं वास्तव में सराहना करता हूं:

// यह प्रस्ताव 2 के बिजनेस रूल 5 के लिए लागू किया गया

या जो कुछ भी आप अपनी आवश्यकताओं को इकट्ठा करने के लिए उपयोग करते हैं।

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

यह छोटी टीमों के साथ मदद नहीं कर सकता है, लेकिन यदि आपके पास अपनी आवश्यकताओं को विकसित करने वाले विश्लेषक हैं, तो यह अमूल्य हो सकता है।

Comments

हालांकि यह अलग है क्योंकि यह एक ट्रैसबिलिटी प्रदान करता है जो कि संस्करण नियंत्रण के लिए ऑर्थोगोनल है: कोड और आवश्यकता विनिर्देश के बीच संबंध जो इसे लागू करता है।

— कज़

ऐसी प्रणाली में जहां संस्करण नियंत्रण बग / आवश्यकताओं प्रणाली के साथ युग्मित होता है, पूर्ण ट्रेसबिलिटी टिप्पणी की आवश्यकता के बिना प्रदान की जाती है। यह कभी-कभी दूसरे तरीके से काम करने में मददगार होता है। SCM की एक फ़ाइल को देखते हुए, मुझे बताएं कि कब क्या लागू किया गया था। या, एक आवश्यकता को देखते हुए मुझे इसे लागू करने के लिए संशोधित सभी फ़ाइलों को दिखाएं।

— आइल

Answer 5

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

Answer 6

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

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

बहुत कम अपवादों के साथ, ट्रैकिंग और मुद्दे को संदर्भित करना VCS, IMNSHO का काम है।

Answer 7

मैं आमतौर पर इस नियम का पालन करता हूं: यदि परिवर्तन स्पष्ट है और परिणामस्वरूप कोड सवाल नहीं उठाता है, तो किसी भी पिछले व्यवहार को पर्याप्त रूप से नहीं बदलता है या बदल देता है - तो इसे बग नंबर और अन्य परिवर्तन जानकारी ट्रैक करने के लिए वीसीएस पर छोड़ दें।

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

Answer 8

संस्करण-नियंत्रण-संबंधी टिप्पणियां स्रोत फ़ाइल में नहीं हैं। वे केवल अव्यवस्था जोड़ते हैं। चूँकि उन्हें संभवतः उसी स्थान पर रखने की आवश्यकता होती है (जैसे फ़ाइल के शीर्ष पर एक टिप्पणी ब्लॉक) वे समानांतर शाखाओं के विलय होने पर टिप्पणी-केवल उपद्रव संघर्ष का कारण बनेंगे।

किसी भी ट्रैकिंग जानकारी को संस्करण नियंत्रण से बाहर निकाला जा सकता है जिसे कोड के शरीर में डुप्लिकेट नहीं किया जाना चाहिए। यह आरसीएस चेकआउट कीवर्ड जैसे मूर्खतापूर्ण विचारों $Log$और इसके ilk के लिए जाता है।

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

लिनक्स कर्नेल में कुछ पुरानी फ़ाइलों में बड़े इतिहास टिप्पणी ब्लॉक हैं। वे तारीखें जब कोई संस्करण नियंत्रण प्रणाली नहीं थी, बस तारकोल और पैच थे।

Answer 9

कोड में टिप्पणियां न्यूनतम और सटीक होनी चाहिए। दोष जोड़ना / जानकारी बदलना मूल्यवान नहीं है। आपको इसके लिए संस्करण नियंत्रण का उपयोग करना चाहिए। कुछ समय संस्करण नियंत्रण परिवर्तन का थोड़ा बेहतर तरीका प्रदान करता है- हम ClearCase UCM का उपयोग करते हैं; UCM गतिविधियाँ दोष संख्याओं, परिवर्तन क्षेत्र आदि (जैसे defect29844_change_sql_to_handle_null) के आधार पर बनाई जाती हैं।

विस्तृत टिप्पणियों को चेक-इन टिप्पणियों में पसंद किया जाता है।

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

प्रामजिक प्रोग्रामर और क्लीनकोड निम्नलिखित दिशानिर्देशों की ओर जाता है

निम्न-स्तरीय ज्ञान को कोड में रखें, जहाँ यह है, और अन्य, उच्च-स्तरीय स्पष्टीकरण के लिए टिप्पणियों को आरक्षित करें।