क्या इनलाइन द्वारा 'एडिट' किए गए हैं, दुकानों में आदर्श है जो संशोधन नियंत्रण का उपयोग करते हैं?

Question

हमारी दुकान के वरिष्ठ देव इस बात पर जोर देते हैं कि जब भी कोड को संशोधित किया जाता है, तो जिम्मेदार प्रोग्रामर को एक इनलाइन टिप्पणी जोड़ना चाहिए जिसमें कहा गया हो कि उसने क्या किया। ये टिप्पणियां आमतौर पर दिखती हैं// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

हम संशोधन नियंत्रण के लिए टीएफएस का उपयोग करते हैं, और मुझे ऐसा लगता है कि इस तरह की टिप्पणियां इनलाइन शोर के बजाय चेक-इन नोट्स के रूप में अधिक उपयुक्त हैं। TFS भी आपको एक या अधिक बग के साथ चेक-इन को जोड़ने की अनुमति देता है। हमारी कुछ पुरानी, ​​अक्सर संशोधित वर्ग फाइलें ऐसी दिखती हैं जैसे उनके पास टिप्पणी-टू-एलओसी अनुपात 1: 1 है। मेरी नज़र में, इन टिप्पणियों से कोड को पढ़ना और शून्य मान जोड़ना कठिन हो जाता है।

क्या यह अन्य दुकानों में एक मानक (या कम से कम सामान्य) अभ्यास है?

Comments

मैं आपसे सहमत हूँ, कि संस्करण नियंत्रण में संशोधन लॉग किसके लिए हैं।

— TZHX

संस्करण नियंत्रण से पहले आपकी टीम के वरिष्ठ देव ने इसका व्यापक प्रसार किया था, और यह अहसास नहीं हुआ कि यह कोड गंध को दूर करने के लिए कहीं और है। उसे छह ओपन-सोर्स प्रोजेक्ट दिखाएं जो बगज़िला और वीसी सिस्टम का उपयोग करते हैं, उससे पूछें कि क्या उसे jQuery लाइब्रेरी की टिप्पणियों में जानने की ज़रूरत है कि $ .axax () को हाल ही में 4 महीने पहले jaubourg द्वारा बदला गया था, और सभी छोटे बदलाव। सैकड़ों लोगों द्वारा किए गए भी वहाँ से संबंधित हैं। संपूर्ण jQuery लाइब्रेरी टिप्पणियों की गड़बड़ी होगी, और कुछ भी प्राप्त नहीं हुआ था!

— गुप्त

हमारे पास वास्तव में स्रोत कोड में बिना नाम की एक अलिखित नीति है क्योंकि यह कोड-स्वामित्व की भावना पैदा कर सकती है जिसे बैडिंग टीएम माना जाता है।

— स्टीफन पॉल्जर 13

Answer 1

मैं आमतौर पर इस तरह की टिप्पणियों को एक बुरा व्यवहार मानता हूं और मुझे लगता है कि इस तरह की जानकारी एससीएम प्रतिबद्ध लॉग्स की है। यह ज्यादातर मामलों में कोड को पढ़ना मुश्किल बनाता है।

हालाँकि , मैं अभी भी विशिष्ट प्रकार के संपादन के लिए अक्सर ऐसा कुछ करता हूं।

केस 1 - कार्य

यदि आप ग्रहण, नेटबीन्स, विजुअल स्टूडियो जैसी आईडीई का उपयोग करते हैं (या किसी अन्य चीज़ के साथ अपने कोडबेस पर पाठ खोज करने का कोई तरीका है), तो शायद आपकी टीम कुछ विशिष्ट "टिप्पणी टैग" या "कार्य टैग" का उपयोग करती है। किस मामले में यह उपयोगी हो सकता है।

मैं समय-समय पर, जब कोड की समीक्षा कर रहा हूं, तो निम्न जैसा कुछ जोड़ें:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

या:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

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

केस 2 - 3-पार्टी लिबस पैच

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

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

केस 3 - गैर-स्पष्ट सुधार

यह एक और अधिक विवादास्पद है और आपके वरिष्ठ देव के लिए क्या पूछ रहा है।

इस समय मैं जिस उत्पाद पर काम कर रहा हूं, उसमें हम कभी-कभी (निश्चित रूप से सामान्य बात नहीं) जैसी टिप्पणी करते हैं:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

हम केवल ऐसा करते हैं यदि बगफिक्स गैर-स्पष्ट है और कोड असामान्य रूप से पढ़ता है। यह उदाहरण के लिए ब्राउज़र क्विर्क के लिए मामला हो सकता है, या सीएसएस अस्पष्टता को ठीक करता है जिसे आपको केवल इसलिए लागू करने की आवश्यकता है क्योंकि किसी उत्पाद में दस्तावेज़ बग है। तो सामान्य तौर पर हम इसे अपने आंतरिक मुद्दे रिपॉजिटरी से जोड़ेंगे, जिसमें तब बाहरी उत्पाद के बग के प्रलेखन के लिए बगफिक्स और पॉइंटर्स के पीछे विस्तृत तर्क शामिल होंगे (जैसे, एक प्रसिद्ध इंटरनेट एक्सप्लोरर 6 दोष के लिए एक सुरक्षा सलाहकार, या ऐसा कुछ)।

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

---

यह सिर्फ में: एक वास्तविक जीवन उदाहरण

कुछ मामलों में, यह कुछ भी नहीं से बेहतर है :)

मैं अभी अपने कोडबेस में एक विशाल सांख्यिकीय संगणना वर्ग में आया था, जहाँ हेडर टिप्पणी सामान्य याद्दा यद के साथ चैंज के रूप में थी: समीक्षक, तिथि, बग आईडी।

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

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

तो उस मामले में मैंने अभी भी इन बुरे व्यवहारों पर विचार किया था, लेकिन लड़का खुश था कि मूल देव ने कम से कम उन्हें अंदर डाल दिया था! कोड के बजाय स्पष्ट रूप से टिप्पणी करना बेहतर होगा, लेकिन मुझे लगता है कि कुछ भी नहीं से बेहतर था।

Comments

ये हालात समझ में आते हैं। इनपुट के लिए धन्यवाद।

— जोशुआ स्मिथ

दूसरा मामला एक साधारण कोड टिप्पणी है कि क्यों कोड में एक पैच है। पहला मामला एक वैध है: सिर्फ एक टिप्पणी कि कोड खत्म नहीं हुआ है या उस हिस्से पर कुछ और काम करना है।

— सालंदूर

वैसे मेरे काम के स्थान पर वरिष्ठ डेवलपर (मुझे) कहते हैं कि परिवर्तन आपके सॉफ़्टवेयर कॉन्फ़िगरेशन प्रबंधन प्रणाली की प्रतिबद्ध टिप्पणियों में चलते हैं। आप अपने SCM और दोष ट्रैकर्स एक साथ झुका है, है ना? (google SCMBUG) स्वचालित रूप से क्या किया जा सकता है मैन्युअल रूप से मत करो।

— टिम विस्क्राफ्ट 20

@ समय: ठीक है, मैं आपसे सहमत हूं, जैसा कि उत्तर की पहली पंक्ति कहती है। लेकिन गैर-स्पष्ट मामलों में, प्रोग्रामर (आलस से बाहर, मुझे लगता है, क्योंकि वे इस पर समय बर्बाद नहीं करना चाहते हैं) प्रतिबद्ध लॉग की जांच नहीं करेंगे और कुछ महत्वपूर्ण जानकारी को याद करेंगे, जबकि 10char टिप्पणी उन्हें इंगित कर सकती है सही बग आईडी जिसमें स्वयं उस बग से संबंधित संशोधन के लॉग होंगे यदि आपने अपना एससीएम और ट्रैकर एक साथ काम करने के लिए सेट किया था। सभी दुनिया के सर्वश्रेष्ठ, वास्तव में।

— केश विन्यास

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

— jwenting

Answer 2

हम संस्करण नियंत्रण के तहत फ़ाइलों के लिए उस अभ्यास का उपयोग करते हैं। हमारे पास आरपीजी कार्यक्रम हैं जो एक मेनफ्रेम पर चलते हैं, और यह उन्हें वापस करने के मुकाबले बहुत अधिक करना मुश्किल साबित हुआ है।

संस्करण स्रोत कोड के लिए, हम चेक-इन नोट्स का उपयोग करते हैं। मुझे लगता है कि जहां वे हैं, कोड को अव्यवस्थित करना नहीं। यह मेटाडेटा है, सब के बाद।

Comments

मैं मानता हूं, संस्करण नियंत्रण के अंतर्गत नहीं आने वाली फाइलें एक अलग कहानी हैं।

— जोशुआ स्मिथ

"उन्हें वापस करने से ज्यादा कुछ करना मुश्किल साबित हुआ।" क्या वास्तव में कोई बहाना मेरी सीटीओ के पेट में नहीं जाएगा।

— टिम विस्क्राफ्ट 20

@ समय: हमेशा सुझावों के लिए खुला - मैं उन्हें कमांड की श्रृंखला को किक कर सकता हूं। :) फ़ाइलों को प्राप्त करने और चालू करने के लिए मेनफ्रेम के साथ काम करना कठिन है।

— माइकल के

मेरा सुझाव - संभवतः आप उन्हें (बैकअप) बंद कर सकते हैं; क्यों न सिर्फ उस जगह को डुबाया जाए और हर रात एक छोटे से लिपि के बदलाव को मर्क्यूरियल में बदल दिया जाए?

— व्याट बार्नेट

Answer 3

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

सौभाग्य से, मेरे प्रबंधक तब से इस बारे में अधिक जानकार हैं कि संस्करण नियंत्रण प्रणाली क्या कर सकती है (मुझे यह जोड़ना होगा कि हमने उस पहली दुकान में SourceSafe का इस्तेमाल किया था)। इसलिए मैं कोड में मेटाडाटा का संस्करण नहीं जोड़ता।

Answer 4

यह आमतौर पर आवश्यक नहीं है यदि आपका एससीएम और आईडीई आपको "शो एनोटेशन" (इसे एक्लिप्स में कहा जाता है) का उपयोग करने की अनुमति देता है, तो आप आसानी से देख सकते हैं कि किसने (ओं) ने कोड का एक टुकड़ा बदल दिया है, और कमेंट में बताया जाना चाहिए कि कौन और क्यों।

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

Comments

"आपको यह समझने की उम्मीद नहीं है" कोड में डालने के लिए संभवतः एक खराब टिप्पणी है। फिर से, मैं कहूंगा कि अपने SCM और बग ट्रैकर्स को एक साथ लिंक करें।

— टिम विस्क्रॉफ्ट

Answer 5

जाहिर है, ऐसी कोई भी टिप्पणी समय के साथ गलत होने की गारंटी है; यदि आप एक पंक्ति को दो बार संपादित करते हैं, तो क्या आप दो टिप्पणियाँ जोड़ते हैं? वह कहाँ जा रहे है? तो एक बेहतर प्रक्रिया अपने उपकरणों पर भरोसा करना है।

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

आपको यह समझने की आवश्यकता है कि वह इस पर भरोसा क्यों नहीं कर सकता है। क्या यह पुरानी आदतें हैं? SCM सिस्टम के साथ एक बुरा अनुभव? एक प्रस्तुति प्रारूप जो उसके लिए काम नहीं करता है? हो सकता है कि वह 'git blame' और Perforce के टाइमलाइन व्यू जैसे टूल के बारे में भी नहीं जानता हो (जो अनिवार्य रूप से यह दिखाता है, हालांकि यह नहीं दिखा सकता है कि किस मुद्दे ने बदलाव को गति दी)।

आवश्यकता के उसके कारण को समझे बिना, आप उसे मना नहीं पाएंगे।

Answer 6

मैं एक 20 + वर्ष पुराने विंडोज उत्पाद पर काम करता हूं। हमारे पास एक समान अभ्यास है जो लंबे समय से जगह में है। मैं इस बात की संख्या नहीं गिन सकता कि इस अभ्यास ने मेरी बेकन को बचाया है।

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

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

एक दोष संख्या के साथ एक टिप्पणी मुझे कोड की उत्पत्ति को देखने के लिए जाने की जगह देती है।

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

Answer 7

यदि आपके पास वीसीएस है, तो टिप्पणियों में हर बदलाव का उल्लेख करना व्यर्थ है। विशिष्ट लाइन से संबंधित एक विशिष्ट बग या अन्य महत्वपूर्ण नोट का उल्लेख करना उपयोगी है। एक परिवर्तन में एक ही प्रतिबद्ध संदेश के तहत कई परिवर्तित लाइनें शामिल हो सकती हैं।

Answer 8

ऐसा नहीं कि मैं बता सकता हूं।

मैं अपने कोड में TODOs को अलग-अलग करता हूं, जैसा कि मैं साथ जाता हूं, और लक्ष्य उन्हें समीक्षा के समय से हटा दिया है।