क्या अधिक टिप्पणियां हाई-टर्नओवर वातावरण में बेहतर हैं?

Question

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

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

Comments

आपको क्या लगता है जब आप किसी अलग प्रोजेक्ट या अलग काम पर जाते हैं और किसी और को अपना कोड मेंटेन करना होता है? क्या आपका कोड वास्तव में इतना साफ और स्पष्ट है कि कोई और आसानी से समझ जाएगा कि आप क्या कर रहे थे और क्यों कर रहे थे?

— कालेब

मौजूदा जवाबों में बहुत सारे अच्छे हैं। लेकिन सिर्फ यह कहना चाहता था कि अगर अब / कुछ यूनिट परीक्षण हैं, तो उच्च टर्नओवर वाले वातावरण के लिए, भवन परीक्षणों में समय का निवेश करें, टिप्पणियों का नहीं। यदि टिप्पणियों के लिए समय बचा है, तो कोड और परीक्षणों दोनों में 'क्यों' टिप्पणियां जोड़ें।

— जेम्स यंगमैन

@ कालेब भले ही यह साफ और स्पष्ट नहीं था, क्या आपको लगता है कि सभी जगह टिप्पणी करने से मदद मिलेगी? सिर्फ विवरणों के साथ कहीं और कुछ दस्तावेज क्यों नहीं लिखे?

— joshin4colours

Answer 1

टिप्पणियाँ कोड को अव्यवस्थित नहीं करती हैं।

और जब वे करते हैं, ठीक है, हर आधा सभ्य आईडीई टिप्पणियों को छिपा / मोड़ सकता है। आदर्श रूप से कहानी को आपके कोड, आपकी आवश्यकताओं के दस्तावेज़, आपके प्रतिबद्ध इतिहास और आपकी इकाई परीक्षणों द्वारा बताया जाना चाहिए, न कि टिप्पणियों द्वारा। हालाँकि अत्यधिक टिप्पणी केवल तभी आहत कर सकती है जब टिप्पणियां कैसे और क्यों नहीं पर केंद्रित हैं, हालांकि यह एक अलग चर्चा है ।

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

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

Comments

+1 को Excessive commenting can only hurt when comments are concentrated on the how and not the whyछोड़कर, मैं इसे एक कदम आगे बढ़ाऊंगा और कहूंगा कि कोई भी टिप्पणी खराब है जब वे बताते हैं कि इसके बजाय क्यों ।

— maple_shaft

Comments don't clutter the code.वैसे यह निर्भर करता है, खासकर यदि आप उपयोग कर रहे हैं #।

— डायनामिक

Answer 2

उस तरह के वातावरण में विपुल टिप्पणियाँ एक समस्या के लिए कवर कर रही हैं जिसे दूसरे तरीके से हल किया जाना चाहिए।

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

इसलिए, जो समस्या वह हल कर रही है, वह यह है कि उसे उन छात्रों के साथ काम करना है जो अपने कोड को पठनीय तरीके से लिखना नहीं जानते हैं। मेरी राय में, टिप्पणियों के साथ कोड को अव्यवस्थित करना उस समस्या का एक कमजोर समाधान है।

स्ट्रिंग कोड समीक्षाएँ बहुत अधिक प्रभावी होंगी, दोनों कोड को ठीक रखने और भविष्य के लिए उन छात्रों को सुधारने में, चाहे वह एक ही कंपनी में हों या कहीं और।

Comments

एक पूरी तरह से कोड की समीक्षा एक डेवलपर द्वारा अत्यधिक टिप्पणियों पर सवाल उठाना चाहिए, लेकिन आप पूरी तरह से सही हैं कि उनकी टीम नियमित टिप्पणियों की तुलना में नियमित कोड समीक्षाओं से बहुत अधिक लाभान्वित होगी।

— maple_shaft

"गुणवत्ता, पठनीय कोड को यह बताने के लिए कभी भी अतिरिक्त टिप्पणियों की आवश्यकता नहीं होनी चाहिए।" - जो कोड लिखे गए 90% के लिए सही नहीं है।

— ओलिवर वीलर

@ ऑलिवर वेबर: तो लिखे गए 90% कोड एक अच्छे कोड की समीक्षा कर सकते हैं। मेरे पास एक टीम में 5 वरिष्ठ डेवलपर्स हैं जहां सभी कोड की समीक्षा कम से कम एक अन्य वरिष्ठ द्वारा की गई थी और उन्होंने कम से कम टिप्पणी के साथ बहुत ही पठनीय कोड का उत्पादन किया है।

— पीडीआर

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

— डेव

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

— पीडीआर

Answer 3

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

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

Answer 4

"हाई-टर्नओवर वातावरण में अधिक टिप्पणियां बेहतर हैं?"

मुझे लगता है कि वे अच्छी तरह से बदतर हो सकते हैं:

• विभिन्न लेखक विभिन्न शैलियों और विवरणों के स्तरों का उपयोग करेंगे और अन्य लोगों द्वारा टिप्पणियों को अपडेट करने में कम होंगे।

• "क्या टिप्पणी की जरूरत है" की राय व्यक्ति से दूसरे व्यक्ति में बदलती है।

• वे कोड लिखने का अभ्यास जारी रखते हैं जो वर्णनात्मक नामों के साथ कोड को पढ़ने में आसान के विपरीत इसे समझाने के लिए टिप्पणियों के साथ पढ़ना मुश्किल है।

• उनके प्रारूप और निरंतरता को बनाए रखना अपने आप में एक काम बन जाता है।

• नए उपयोगकर्ताओं को त्वरित परिवर्तन करने में सक्षम होने से पहले 'प्रारूप' मानक सीखना होगा।

Comments

आपके द्वारा सूचीबद्ध किए गए मुद्दे भी कोड के लिए एक उच्च कारोबार वातावरण में ही मुद्दे हैं, न कि केवल टिप्पणियां। यह ... दिलचस्प है;) एक कोड / टिप्पणियों की समस्या से अधिक लोगों की समस्या।

— यानि

+1 हाय यानिस, हाँ यह बहुत अच्छी बात है। मैं सहमत हूँ। मुझे यह भी लगता है कि क्योंकि कोड ही थोड़ा अधिक संरचित है - कुछ चीजों के लिए निश्चित नाम हैं, सबसे सरल उदाहरण - एक फ़ंक्शन "to_string" में कोई अस्पष्टता नहीं है, इसे कहा जाना चाहिए, जहां टिप्पणियों के रूप में बिल्कुल शून्य संरचना है या शर्तों पर सहमति व्यक्त की गई है , कि टिप्पणी परेशान करती है। फिर कोड बहुत अधिक 'स्पेगेटी' के साथ समाप्त हो सकता है फिर टिप्पणी करता है। दिलचस्प।

— माइकल दुरंत

Answer 5

बिंदु 1: उच्च कारोबार वाले वातावरण में स्पष्टता महत्वपूर्ण है

बिंदु 2: शब्दशः स्पष्टता नहीं है

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

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

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

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

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

Answer 6

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

एक और महान धागा है जो कवर करता है कि क्या टिप्पणियाँ प्रलेखन हैं या नहीं।

Answer 7

टिप्पणियाँ दूसरों की तुलना में कुछ परिदृश्यों में अधिक सहायक होती हैं। यह इतना मौलिक है कि मुझे इस बात की चिंता है कि इतने सारे उत्तरों के बीच मैं इसे कैसे समझाऊं जो मुझे "टिप्पणी विरोधी" लगता है।

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

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

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