इनलाइन कोड टिप्पणियों के लिए सबसे अच्छा तरीका क्या है?

Question

हम 20 साल की विरासत कोडबेस के लिए कुछ रिफैक्टिंग कर रहे हैं, और मैं अपने सहकर्मी के साथ कोड में टिप्पणी प्रारूप (plsql, java) के बारे में चर्चा कर रहा हूं।

टिप्पणियों के लिए कोई डिफ़ॉल्ट प्रारूप नहीं है, लेकिन ज्यादातर मामलों में लोग टिप्पणी में ऐसा कुछ करते हैं:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

भविष्य और पिछली टिप्पणियों के लिए प्रस्तावित प्रारूप जो मुझे चाहिए:

// {yyyy-mm-dd}, unique_author_company_id, comment

मेरे सहयोगी का कहना है कि हमें केवल टिप्पणी की आवश्यकता है, और इस प्रारूप में सभी अतीत और भविष्य की टिप्पणियों को सुधारना चाहिए:

// comment

मेरे तर्क:

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

मेरे सहकर्मी के तर्क:

• इतिहास SCM में है
• डेवलपर्स को कोड में सीधे कोड के इतिहास के बारे में पता नहीं होना चाहिए
• पैकेजों को 15k लाइनें लंबी और असंरचित टिप्पणियां मिलती हैं जिससे ये पैकेज समझने में कठिन हो जाते हैं

आपको क्या लगता है कि सबसे अच्छा तरीका क्या है? या फिर आप इस समस्या को हल करने के लिए एक बेहतर दृष्टिकोण क्या है?

Comments

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

— कार्ल बेज़ेलफेल्ट

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

— रॉबर्ट हार्वे

आपको अपनी SCM प्रक्रिया या टूलसेट में सुधार करना होगा। और डेवलपर्स को हर पंक्ति को बदलने से डरना चाहिए चाहे वह कितनी भी पुरानी हो।

— किर्क ब्रॉडहर्स्ट

मैं आपके सहकर्मी के साथ 100% सहमत हूँ

— wim

Answer 1

सामान्य टिप्पणियाँ

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

उसी तरह तारीख / लेखकइन्फो आपको इस बात के संदर्भ में कुछ भी हासिल नहीं करता है कि कोड इस तरह क्यों किया गया था; ठीक उसी तरह जैसे यह समय के साथ पतित हो सकता है क्योंकि किसी भी उपकरण द्वारा कोई प्रवर्तन नहीं है। स्रोत नियंत्रण प्रणाली में भी वही जानकारी पहले से संग्रहीत है (इसलिए आप प्रयास को दोहरा रहे हैं (लेकिन कम विश्वसनीय तरीके से)।

तर्कों के माध्यम से जाना:

मैं रखरखाव के कारणों के लिए कहता हूं, यह जानना महत्वपूर्ण है कि कब और किसने बदलाव किया (यहां तक ​​कि यह जानकारी एससीएम में है)।

क्यों। इन बातों में से किसी ने भी मुझे कोड बनाए रखने के लिए महत्वपूर्ण हड़ताल नहीं की। यदि आपको लेखक से बात करने की आवश्यकता है तो स्रोत नियंत्रण से यह जानकारी प्राप्त करना अपेक्षाकृत सरल है।

कोड के पास जीवन है इस कारण से एक इतिहास था।

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

क्योंकि परिवर्तन की तारीख के बिना यह जानना असंभव है कि SCM टूल को खोले बिना और लॉन्ग ऑब्जेक्ट हिस्ट्री में सर्च किए बिना कब बदलाव किया गया।

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

क्योंकि लेखक बहुत महत्वपूर्ण है, ऑर्टरी का एक परिवर्तन ऑर्टोरी के परिवर्तन की तुलना में अधिक विश्वसनीय है

सभी लेखक (अपने से अलग) समान रूप से विश्वसनीय हैं।

चपलता कारणों से, एक नेविगेट खोलने के लिए कोई जरूरत नहीं एससीएम उपकरण

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

लोग कुछ ऐसा करने से डरेंगे जो किसी ने 15 साल पहले किया था, जो कि कुछ समय से पहले किया गया था ...

यदि कोड 15 साल तक चला है, तो यह अधिक ठोस होने की संभावना है, फिर कोड जो बिना समीक्षा के केवल 6 महीने तक चला है। स्थिर कोड स्थिर रहने के लिए जाता है, छोटी गाड़ी का कोड समय के साथ अधिक जटिल हो जाता है (जैसा कि यह छोटी गाड़ी है समस्या यह है कि पहले सोचा के रूप में सरल नहीं है)।

जानकारी प्राप्त करने के लिए स्रोत नियंत्रण का उपयोग करने का और भी कारण।

इतिहास SCM में है

हाँ। सबसे अच्छा कारण अभी तक।

डेवलपर्स को कोड में सीधे कोड के इतिहास के बारे में पता नहीं होना चाहिए

अगर मुझे वास्तव में इस जानकारी की आवश्यकता है तो मैं इसे स्रोत नियंत्रण में देखूंगा।
अन्यथा यह प्रासंगिक नहीं है।

संकुल को 15k लाइनें लंबी और असंरचित टिप्पणियाँ मिलती हैं जो इस पैकेज को समझने में कठिन होती हैं

टिप्पणियों का वर्णन होना चाहिए कि आप कुछ भी क्यों कर रहे हैं।
टिप्पणियों का वर्णन नहीं किया जाना चाहिए कि कोड कैसे काम करता है (जब तक कि एल्गोरिथ्म स्पष्ट नहीं है)।

Comments

आपकी प्रतिक्रिया के लिए tks, मेरी बात को बदलने के लिए पर्याप्त तर्क हैं :)

— डिएगो अल्वारेज़

+1। बस एक जोड़: एक पाठ संपादक (या गलती से, या चूक, या जो भी हो) की तुलना में स्रोत नियंत्रण में झूठ बोलना बहुत कठिन है।

— टेम्डमर्स

अगर हम कहते हैं कि केवल आठ महीने पहले हमने plsql के लिए SCM टूल का उपयोग करना शुरू कर दिया था, और कोड में 20 साल हैं, तो आपको क्या लगता है अगर हम लेखक और तारीख को उन परिवर्तनों की ऐतिहासिक टिप्पणियों से हटा दें जो SCM में नहीं हैं? इसका कोई मतलब है? या इस समय कोई मतलब नहीं है कि 15-20 साल पहले कौन और कब बदलाव किया गया था? आप समय और प्रतिक्रिया के लिए tks।

— डिएगो अल्वारेज़

Answer 2

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

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

आखिरकार, आप प्रोग्रामर को किराए पर लेते हैं, कहानी कहने वाले को नहीं;; ⇒