मैं एक टीम के सदस्य के साथ कैसे व्यवहार कर सकता हूं जो कोड में टिप्पणी करना पसंद नहीं करता है?

182

मेरी टीम का एक सदस्य लगातार उसके कोड में टिप्पणी करने से बचता है।

उनका कोड स्व-दस्तावेजीकरण नहीं है, और अन्य प्रोग्रामर को उनके कोड को समझने में मुश्किल समय लगता है।

मैंने उनसे कई बार अपने कोड पर टिप्पणी करने के लिए कहा है, हालांकि वह सिर्फ बहाने देता है या दावा करता है कि वह बाद में करेगा। उनकी चिंता यह है कि टिप्पणियों को जोड़ने में बहुत अधिक समय लगेगा और परियोजनाओं में देरी होगी।

उसे अपने कोड को ठीक से दस्तावेज़ित करने के लिए मनाने के लिए मैं उसे क्या तर्क दे सकता हूँ?

उस नोट पर, क्या मैं कोड टिप्पणियों पर ध्यान देना गलत हूं या क्या यह एक बड़ी समस्या का संकेत है जिसे संबोधित किया जाना चाहिए?

teamwork team comments

— महबूब आर आरमन
स्रोत

109

टिप्पणियों के लिए टिप्पणी करना कोड को बेहतर नहीं बनाता है। यदि कोड बिना समझे (क्यों सहित) समझ में आता है तो ठीक है अन्यथा टिप्पणी करें।

— मार्टिन यॉर्क

63

ओह, हाँ, और जब एक दौड़ की स्थिति या गतिरोध को हल करने के लिए कोड ट्रिपल के कुछ टुकड़े की जटिलता, उस पर टिप्पणी न करें! लोगों को इस पहेली को सुलझाने दें कि कोड को जिस तरह से होना चाहिए, वह क्यों होता है, और यदि वे प्रयोगात्मक परिवर्तन करते हैं तो रहस्यमय तरीके से क्यों टूटते हैं। हर किसी को संगोष्ठी का शतरंज ग्रैंडमास्टर होना चाहिए ...

— कज़

12

@ काज सरकास्म (मुझे उम्मीद है) पाठ के लिए अच्छी तरह से अनुवाद नहीं करता है।

— डेवॉर्ड

10

@deworde & artjom - हाँ, यह व्यंग्य है। नहीं, यह उतनी सफाई से नहीं आता जितना कि यह हो सकता है, लेकिन यह स्पष्ट रूप से व्यंग्य है।

17

निम्नलिखित डेल कार्नेगी के सिद्धांत आप को समझने के लिए क्यों वह उल्लेख किया comment..you है कि वह नहीं करना चाहते हैं नहीं करना चाहती की कोशिश करनी चाहिए देरी project..so आप उसे करने के लिए कह सकते हैं कि अगर वह टिप्पणी नहीं करता है अन्य का नहीं होगा कोड को समझने में सक्षम है और इससे परियोजना में और देरी होगी..तो निश्चित रूप से मदद करनी चाहिए ..

— अनिरुद्ध

430

अकेले टिप्पणियाँ बेहतर कोड के लिए नहीं बनती हैं, और केवल "अधिक टिप्पणियों" के लिए जोर देने से आपको /* increment i by 1 */स्टाइल टिप्पणियों की तुलना में थोड़ा अधिक देने की संभावना है ।

तो अपने आप से पूछें कि आप उन टिप्पणियों को क्यों चाहते हैं। "यह सबसे अच्छा अभ्यास है" एक तर्क के रूप में तब तक नहीं गिना जाता जब तक कि आप क्यों नहीं समझते।

अब, टिप्पणियों का उपयोग करने का सबसे हड़ताली कारण यह है कि कोड को समझना आसान है, और जब लोग टिप्पणियों की कमी के बारे में शिकायत करते हैं, तो वे या तो क्लूलेस तोते हैं, या उन्हें उस कोड को समझने में कठिन समय लगता है जिसके साथ वे काम कर रहे हैं।

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

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

लोगों के कौशल के मोर्चे पर, हर कीमत पर कृपालु या आरोप लगाने से बचें; अपने सवालों के बारे में गंभीर और ईमानदार रहें।

— टैडमर्स
स्रोत

269

+1 के लिए "लापता टिप्पणियों की शिकायत न करें: अपठनीय कोड के बारे में शिकायत करें।"

— एमडी महबूबुर्रहमान

4

क्या होगा यदि कोड के बारे में किसी भी प्रश्न का उत्तर "इसे समझने के लिए आपने क्या किया है?"

— शाऊल

40

+1: पठनीय फ़ंक्शन नामों के लिए पुश करने से लाभ जुड़ सकते हैं ... कोड समीक्षा में: "समझ नहीं सकते कि xg_jkhsfkasq क्या कर रहा है"। "ओह, यह प्राथमिक फ़ीड बफर को फ्लश कर रहा है, अब मैं जारी कर सकता हूं?" "निश्चित रूप से, लेकिन जब तक आपने फ़ंक्शन का नाम बदलकर flush_primary_buffer" नहीं किया, तब तक मैं इसे स्वीकार करने में संकोच कर रहा हूं "", लेकिन यह मुख्य कैश को भी साफ़ कर रहा है, इसलिए यह नाम भ्रामक होगा "" क्या यह कैश स्पष्ट नहीं है? 'आप सिस्टम को रोक देंगे! जबकि आप उस तर्क को बदल रहे हैं, क्या आप उस फ़ंक्शन का नाम बदलना चाहेंगे? "

— डेवॉर्ड

18

मैं यह धारणा देने के बारे में चिंतित हूं कि मैं कोड पढ़ने में असमर्थ हूं। एक गैर-तकनीकी प्रबंधक केवल यह देख सकता है कि मैं लगातार 'बॉब' से मदद माँग रहा हूँ क्योंकि बॉब का कोड मेरे लिए बहुत उन्नत है। इसका मतलब होगा कि बॉब एक 'उन्नत' डेवलपर है और मैं उसके स्तर पर काम करने के लिए तैयार नहीं हूं।

— रॉब पी।

5

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

— डेवॉर्ड

114

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

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

इसे कुछ महीनों की अवधि में करें, सप्ताह में कम से कम दो बार। यदि आप पर्याप्त भाग्यशाली हैं, तो अन्य देवता इन सत्रों के माध्यम से सीखेंगे ताकि आप समीक्षा आवृत्ति को कम कर सकें।

— डॉक्टर ब्राउन
स्रोत

5

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

— जिमी होफा

1

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

— मार्टिन ब्राउन

27

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

— Earlz
स्रोत

2

+1 - यदि आपको कोड के किसी भाग के बारे में कोई प्रश्न पूछना है तो उस भाग को या तो एक टिप्पणी की आवश्यकता है या फिर एक रिफलेक्टरिंग की आवश्यकता है ताकि प्रश्न भविष्य में किसी और से पूछने की आवश्यकता न हो।

— डंक

+1 भी हैरान कोड / सहकर्मी की समीक्षा के जवाब बहुत कम हैं। टीम स्तर कोड-समीक्षाओं को लागू करना (ताकि किसी व्यक्ति को नहीं चुनना) समस्या को हल करने में मदद कर सकता है (और शायद दूसरों को भी आपको पता नहीं है कि आपके पास :) है। चरम पर आप एक नो-सोलो-पुश पॉलिसी को लागू कर सकते हैं जिसके तहत आपको तब तक पुश करने की अनुमति नहीं दी जाती है जब तक कि आपके परिवर्तनों की समीक्षा किसी अन्य टीम के सदस्य द्वारा नहीं की जाती है।

— क्रिस ली

@ मेरी कंपनी की कोड समीक्षा नीतियों में तकनीकी रूप से लागू नहीं किया गया है, लेकिन एक नीति है कि इससे पहले कि एक कहानी को रेडी फॉर टेस्ट के रूप में चिह्नित किया जा सकता है, कोड की समीक्षा होनी चाहिए, कोई फर्क नहीं पड़ता कि विकास कार्य किसने किया था। यह काफी दिलचस्प है कि सीटीओ जब

— एलओएल

18

यह उस कोड पर निर्भर करता है जो आपकी टीम का कार्यकर्ता करता है। यदि आप अंकल बॉब की क्लीन कोड किताब पढ़ते हैं, तो आप पाएंगे कि वह वास्तव में कोड में टिप्पणी नहीं जोड़ना पसंद करते हैं । यदि कोड स्वयं उतना ही पठनीय है जितना कि होना चाहिए, तो शायद ही किसी टिप्पणी की आवश्यकता हो।

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

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

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

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

— फ्रैंक
स्रोत

टिप्पणी से वास्तविक लाभ पर चर्चा के लिए +1। टिप्पणियाँ स्रोत कोड में मूल्य जोड़ने के लिए होती हैं।

— स्पार्की

1

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

— डंक

3

हमेशा उस पुस्तक के दृष्टिकोण के साथ एक समस्या थी। टिप्पणियाँ एक व्यावसायिक प्रक्रिया / तर्क (या क्यों) की व्याख्या करने में v उपयोगी हो सकती हैं जो कि स्वच्छ कोड की कोई भी राशि नहीं कर सकती है।

— भावल

हालांकि कोड में टिप्पणियां आवश्यक नहीं होंगी, कम से कम विधि का विवरण होना चाहिए, जैसे कि जावदोक

— डेन्यूबियन सेलर

2

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

— गॉर्डन

10

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

उस ने कहा, आप शायद उसकी मदद कर सकते हैं। मेरे अनुभव में, जब कोई विरोध करता है कि टिप्पणी करने में बहुत अधिक समय लगता है तो मनोवैज्ञानिक बाधा जैसे…

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

वे नहीं कर रहे हैं: यह महत्वपूर्ण है एक प्रोग्रामर का एहसास करने के लिए है कि टिप्पणियों परीक्षण की तरह हैं बस - वे प्रोग्रामर खुद के लिए कर रहे हैं भविष्य में उपयोग के लिए। वे उसे अपने दृष्टिकोण के बारे में अलग तरह से सोचने के लिए मजबूर करते हैं।

इसमें से कोई भी CI, परीक्षण या कोड समीक्षाओं का विकल्प नहीं है। यह कोडिंग के कई महत्वपूर्ण हिस्सों में से एक है, जो स्वयं, कोड लिखना नहीं है।

— रेव्स कोजीरो
स्रोत

3

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

— गॉर्डन

@GordonM क्या आपको लगता है कि किसी कर्मचारी को यह बताना बेहतर नहीं होगा कि उसका व्यवहार अनुचित है और निरंतर अनुचित व्यवहार के परिणाम क्या होंगे?

— कोजिरो

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

— गॉर्डन

@GordonM मैं वास्तव में इस निहितार्थ के अपवाद को लेती हूं कि मैंने जो कहा वह धमकी थी, लेकिन फिर भी, मैंने इसे ठीक कर दिया।

— कोजिरो

8

कोड समीक्षा सॉफ़्टवेयर प्राप्त करें, और इसका अच्छी तरह से उपयोग करें।

हम भट्ठा का उपयोग करते हैं, और हम इसे प्यार करते हैं। हमारी एक नीति है कि हर बदलाव की समीक्षा की जानी चाहिए (हालाँकि हम टैग और संघर्ष-कम मर्ज पर devs को स्वयं के लिए समीक्षाएँ बढ़ाने / अनुमोदन करने की अनुमति देते हैं (हालांकि हम में से अधिकांश रिबेसिफ़ का उपयोग करते हैं); इस तरह से हम समीक्षाओं के बिना जल्दी से बदलाव कर सकते हैं)।

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

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

Kiln जैसे सॉफ्टवेयर का उपयोग करने से, कोई भी परिवर्तन अनदेखा नहीं किया जाता है। मेरी देव टीम में हर कोई इसे इस तरह से पसंद करता है। कोड समीक्षा सॉफ़्टवेयर का हमारे कोड गुणवत्ता और अनुप्रयोग गुणवत्ता दोनों पर भारी प्रभाव पड़ा है :-)

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

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

— डैनी टुपनेनी को दिखाया
स्रोत

4

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

टिप्पणियाँ क्यों?

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

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

कोड पठनीयता! = कोड टिप्पणियाँ

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

दूसरी ओर, पठनीय कार्यक्रम = कोड + प्रलेखन में "टिप्पणियों से एपीआई" की पीढ़ी की सुविधा के लिए टिप्पणियों के कई वैध अनुभाग शामिल हो सकते हैं।

कोड शैली मानकों का पालन करें

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

एक कोड पठनीयता इंजीलवादी बनें

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

कोड के हर लाइन पर लागू होने वाली युक्तियों के साथ नामकरण, टिप्पणी और प्रारूपण को सरल बनाएं
जटिलता और भ्रम को कम करने के लिए अपने कार्यक्रम के छोरों, तर्क और चर को परिष्कृत करें
एक स्तर पर एक कार्य करने के लिए कोड के ब्लॉक को पुनर्गठित करने जैसे फ़ंक्शन स्तर पर हमला समस्याओं
प्रभावी परीक्षण कोड लिखें जो पूरी तरह से और संक्षिप्त हो और साथ ही पठनीय हो

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

— याकिमोविच को दर्शाता है
स्रोत

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

— नक्स

1

एक अच्छा इंजीनियर पूरी व्यवस्था की परवाह करता है (सहित गैर codegenerated प्रलेखन।) - लेकिन यहाँ हम, ज़ाहिर है, सामान्य रूप में मन कोडिंग की .. मेरी बात है कि कोड कहा जाता है में पहचानकर्ता नहीं होने foo , बार , tmpSomething2 और IamJustTooSmartAssToCare पहले से ही बेहतर बनाता है स्थिति और समग्र कमी को यह समझाने की जरूरत है कि कोड क्या है और यह क्या करता है। कोड को एक अच्छी तरह से डिज़ाइन किए गए एपीआई की तरह "सोच विधा" पर लिखा जाना चाहिए, जिसे मनुष्य द्वारा पढ़ा, समझा, पुन: उपयोग और रखरखाव किया जाता है। कोड में बहुत सारी टिप्पणियां जो समझना मुश्किल है, बहुत बुरा संकेत है!

— योहान याकिमोविच

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

— योहेन याकिमोविच

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

— नक्स

"अगर आप पठनीयता को प्राथमिकता देते हैं तो आपको टिप्पणियों की आवश्यकता नहीं होगी" - हाँ यह बिल्कुल वही है जो मैं कह रहा हूं (और मुझे पता है कि यह प्राप्त करना आसान नहीं लगता है)। बीटीडब्ल्यू क्या आपके पास ऐसी परिस्थितियां हैं जब इतिहास को पूरा करने (संस्करण नियंत्रण) को "बग / आवश्यकता / कहानी संख्या" पर प्रतिबिंबित करने के लिए पर्याप्त नहीं है? मैं लंबे समय से अभ्यास कर रहा हूं - मेरे लिए काम करता है और विकास के इतिहास से कोड को खाली रखने की अनुमति देता है..यदि यह कम व्यवस्थित रूप से विकसित होता है।

— योहान याकिमोविच

3

क्या मैं कोड टिप्पणियों पर ध्यान देना गलत हूं या क्या यह एक बड़ी समस्या का संकेत है जिसे संबोधित किया जाना चाहिए?

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

तो कैसे करें? डॉक्स ब्राउन के सुझावों के बारे में समीक्षा / रीफैक्टरिंग सत्र एक अच्छा विचार है। मुझे पेयर प्रोग्रामिंग और भी अधिक प्रभावी लगती है, लेकिन इसे लागू करना और भी कठिन हो सकता है।

— पीट
स्रोत

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

— मालाची

3

सबसे पहले, मैं आपको सुझाव दूंगा कि आप टिप्पणियों के बारे में अपने दृष्टिकोण को फिर से संबोधित करें।

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

अधिकांश मामलों में, मैं उनसे मुठभेड़ करता हूं, टिप्पणियां बुराई हैं। मैं रॉबर्ट मार्टिन द्वारा "क्लीन कोड" के कोड कमेंट्स चैप्टर को पढ़ने की सलाह दूंगा कि क्यों उन्हें अच्छी समझ हो।

टिप्पणियाँ आपके कोड को कई तरह से चोट पहुँचाती हैं:

1) उन्हें बनाए रखना मुश्किल है। रिफैक्टरिंग करने पर आपको अतिरिक्त काम करना होगा; यदि आप टिप्पणी में वर्णित तर्क को बदलते हैं, तो आपको टिप्पणी को संपादित करने की भी आवश्यकता है।

2) वे अक्सर झूठ बोलते हैं। आप टिप्पणियों पर भरोसा नहीं कर सकते हैं और इसके बजाय कोड को अवश्य पढ़ें। जो सवाल उठाता है: आपको टिप्पणियों की आवश्यकता क्यों होगी?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(हैश योग नहीं बल्कि उत्पाद है।)

3) टिप्पणियाँ कोड को अव्यवस्थित करती हैं, और बहुत कम ही कोई मूल्य जोड़ते हैं।

मेरा समाधान: अधिक टिप्पणियां जोड़ने के बजाय, उनसे छुटकारा पाने की कोशिश करें!

— पॉल
स्रोत

4

यह सिर्फ मूर्खतापूर्ण है। मुझे आशा है कि किसी को भी विश्वास नहीं होगा कि इस तरह की घटिया टिप्पणी शैली सहायक है। लेकिन क्या आप ईमानदारी से मानते हैं कि टिप्पणियों का इस्तेमाल कभी नहीं किया जाना चाहिए ?

— jmk

1

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

— DBlackborough

3

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

— xaxxon

4

@xaxxon इस बात का उल्लेख नहीं करता है कि भले ही वह व्यक्ति आप हो।

— शराबी

3

@mehaase - नहीं क्या, कैसे नहीं, लेकिन कोड में टिप्पणी जोड़ने का सबसे महत्वपूर्ण कारण क्यों है।

— हेनक लैंगवेल्ड

1

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

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

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

अधिकतर, टीम के सदस्यों को एक-दूसरे से स्पष्टीकरण के लिए कहने के लिए प्रोत्साहित करके कि आप एक आत्म-संतुलन प्रणाली बनाते हैं; जहां अलग-अलग टीम के सदस्य एक-दूसरे को "ऑटो-एडजस्ट" करते हैं।

— ब्रेंडन
स्रोत

1

यह मोटे तौर पर टेम्डर के उत्तर का विस्तार है, लेकिन नियमित अंतराल पर कोड समीक्षा करते हैं।

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

संपादित करें: मैं इस बात के लिए अनिश्चित हूं कि कोई मेरे सुझाव को क्यों ठुकरा देगा - शायद मैंने यह मान लिया था कि कोड समीक्षा के लाभ सामान्य ज्ञान होंगे ... कृपया इस धागे को अभ्यास के सामुदायिक विश्लेषण के रूप में देखें:

क्या कोड अच्छे अभ्यास की समीक्षा कर रहा है?

— संशोधित करता है
स्रोत

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

— Evik James

1

बीत रहा है लोगों को अन्य सहकर्मियों के सामने कोड पर हंसते तरीके से करना नहीं है: - \

— डैनी tuppeny

1

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

— मार्टिन ब्राउन

1

टिप्पणी करने पर अक्सर अत्यधिक विचारों को ध्यान में रखते हुए, मैं वजन करने में संकोच करता हूं। कहा जा रहा है ...

कुछ तर्क हैं जो मैं प्रस्तुत कर सकता हूं कि यदि आप (अपठनीय) कोड लिखने जा रहे हैं कि इसे ठीक से प्रलेखित किया जाना चाहिए?

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

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

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

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

एक तरफ के रूप में ... कुछ प्रलेखन की आवश्यकता कभी-कभी होती है भले ही कोड की "रीडबैलिटी" कितनी अच्छी हो। एपीआई के पास प्रलेखन होना चाहिए, बेहद तकनीकी और जटिल संचालन में शामिल प्रक्रियाओं को समझने में प्रोग्रामर की सहायता करने के लिए दस्तावेज होना चाहिए (अक्सर प्रोग्रामर डोमेन के बाहर ज्ञान), और जटिल रीगेक्स जैसी कुछ चीजें वास्तव में दस्तावेज होनी चाहिए कि आप किसके खिलाफ मिलान कर रहे हैं।

— बिल
स्रोत

0

कई परियोजनाओं को कोड प्रलेखन की आवश्यकता होती है: इंटरफ़ेस दस्तावेज़, डिज़ाइन दस्तावेज़, ...

कुछ परियोजनाओं के लिए आवश्यक है कि इस तरह के दस्तावेज़ीकरण को कोड टिप्पणियों में रखा जाए और उन्हें Doxygen या Sphinx या Javadoc जैसे उपकरणों के साथ निकाला जाए, ताकि कोड और प्रलेखन अधिक सुसंगत रहें।

इस तरह, डेवलपर्स को कोड में उपयोगी टिप्पणी लिखना आवश्यक है और यह कर्तव्य परियोजना नियोजन में एकीकृत है।

— mouviciel
स्रोत

6

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

— Jan Hudec

1

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

— मौविसील

2

खैर, नहीं, यह नहीं है। आप .pdf में कैसे नोटिस करने जा रहे हैं, कि कोड वास्तव में वर्णन की तुलना में कुछ अलग करता है?

— Jan Hudec

1

हो सकता है कि मेरी राय मेरे डोमेन, स्पेस क्रिटिकल सॉफ्टवेयर के पक्षपाती हो, जहां हर चीज की समीक्षा, नियंत्रण, सत्यापन, परीक्षण दो या तीन या चार बार किया जाता है। प्रलेखन की स्वचालित पीढ़ी विसंगतियों को दबाती नहीं है लेकिन यह उन्हें कम करने में मदद करती है।

— मौविसील

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

— Jan Hudec

0

मैं यह बताने जा रहा हूं कि अधिकांश उत्तर और टिप्पणियां किस ओर इशारा करती हैं: आपको अपने कथित समाधान को आगे बढ़ाने की कोशिश करने के बजाय यहां वास्तविक मुद्दे का पता लगाने की आवश्यकता है।

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

— reinierpost
स्रोत

0

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

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

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

— रेव्ह M.S.Nayak
स्रोत

0

कोड की समीक्षा के उत्तरों से प्यार करें, लेकिन शायद मेरी प्रक्रिया थोड़ी मदद करेगी।

मुझे टिप्पणियों से प्यार है, लेकिन मैंने उन्हें पहले पास के कोड में कभी नहीं जोड़ा। शायद यह सिर्फ मेरी शैली है, लेकिन मैं विकास के दौरान कोड के 3 से 5 बार (रीफैक्टरिंग, परीक्षण लिखने, आदि) के समान भाग को मारूंगा।

जब भी मैं थोड़ा भ्रमित हो जाता हूं या जब भी कोई मुझसे कोड के एक खंड के बारे में सवाल पूछता है तो मैं इसे ठीक करने का प्रयास करता हूं ताकि यह समझ में आए।

यह एक टिप्पणी जोड़ने के रूप में सरल हो सकता है अपने स्वयं के फ़ंक्शन में एक भ्रामक संचालन को हटाने या यह एक नई वस्तु निकालने की तरह एक बड़ा रिफैक्टर ट्रिगर कर सकता है।

मेरा सुझाव है कि आप समूह के सभी लोगों को "स्वयं" के लिए प्रोत्साहित करें कि उनका कोड दूसरों के लिए पठनीय है - इसका मतलब है कि हर बार जब कोई आपसे आपके कोड के बारे में सवाल पूछता है, तो आप एक बदलाव करने के लिए प्रतिबद्ध होते हैं - या उसके साथ बेहतर जोड़ी। परिवर्तन को सही बनाने के लिए व्यक्ति!

इसे गंभीरता से अपने "टीम कॉन्ट्रैक्ट" के हिस्से के रूप में आगे बढ़ाने पर विचार करें (और यदि आपके पास एक अनुबंध नहीं है, तो निश्चित रूप से एक अनुबंध बनाएं) - इस तरह से हर कोई इस पर सहमत हो गया है और आपने इसे एक दीवार पर कहीं रख दिया है, ताकि 'isn' हो। आप क्या करने के लिए सहमत हुए हैं, इस बारे में कोई सवाल नहीं करें।

— बिल के
स्रोत

0

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

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

कठोर अनुभव से बेहतर कोई शिक्षक नहीं है!

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

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

— GordonM
स्रोत

-1

उसे टिप्पणियों के बिना कुछ और कोड दें और उसे कोड समझने के लिए कहें। हो सकता है कि वह तब उचित टिप्पणियों के महत्व को समझे।

— अभिषेक गहलोत
स्रोत

12

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

— एक CVn

2

@ माइकलकॉर्जलिंग: यह इस बात पर बहुत निर्भर करता है कि आप किस तरह का कोड लिख रहे हैं। यदि आपका कोड किसी भाषा या एपीआई की असामान्य रूप से ज्ञात विशेषताओं पर निर्भर करता है, या आपने एक अस्पष्ट बग से बचने के लिए काउंटर-सहज तरीके से कुछ किया है जो आपको खोजने में घंटों लग गए, तो इस बारे में टिप्पणी करना बहुत अधिक प्रभावी होगा। इस पृष्ठभूमि की जानकारी w / o टिप्पणियों के बारे में कोड को "स्पष्ट" बनाने का प्रयास करने की तुलना में यह (संभवतः एक लेख के लिए लिंक सहित)।

— लार्स

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

— लार्स

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

— बजे एक CVn

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

— लार्स

-1

क्या यह प्रोग्रामर कुछ कोड रखरखाव करता है। यदि नहीं, तो उसे चाहिए: आपके पास जो भी नापसंद प्रोजेक्ट है, उसकी जांच करें और उसके रखरखाव का जिम्मा उसे सौंप दें।

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

— Arkh
स्रोत

1

चीजों को करने के उचित तरीके से उन्हें प्रशिक्षित करने के बजाय प्रोग्रामर को छोड़ने के लिए यह दृष्टिकोण अधिक पसंद है।

— मार्टिन ब्राउन

-1

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

— agilob
स्रोत

-1

टिप्पणियों का एक उद्देश्य है, और केवल एक उद्देश्य है:

यह कोड यह काम क्यों करता है?

यदि कोई टिप्पणी यह नहीं बताती है कि कुछ ऐसा क्यों है, तो उसे हटा दिया जाना चाहिए। बेकार टिप्पणियां जो कोड को अव्यवस्थित करती हैं वे बेकार से कम हैं, वे सक्रिय रूप से हानिकारक हैं।

मुझे अपनी टिप्पणियों को अपनी आईडीई में सबसे स्पष्ट बात बनाने की आदत है। उन्हें हरे रंग की पृष्ठभूमि पर सफेद पाठ के साथ हाइलाइट किया गया है। वास्तव में आपका ध्यान आकर्षित करता है।

ऐसा इसलिए है क्योंकि कोड बताता है कि कुछ क्या कर रहा है, और टिप्पणी यह है कि यह क्यों कर रहा है। मैं इस पर जोर नहीं दे सकता।

एक टिप्पणी का एक अच्छा उदाहरण:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

एक बुरा उदाहरण:

/* instantiate clsUser */

यदि आप कोड के "सेक्शन" के रूप में टिप्पणियों का उपयोग कर रहे हैं: अपने मैमथ विधि को छोटे, उपयोगी नामित कार्यों में काट दें और टिप्पणियों को हटा दें।

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

यदि आप टिप्पणियों को चेतावनी संदेशों के रूप में उपयोग कर रहे हैं : सुनिश्चित करें कि आप ऐसा क्यों कहते हैं।

— जोनाथन
स्रोत

-2

यहां उत्तरों के पूरक के लिए, मैं "यदि आप चाहते हैं कि यह सही हो जाए तो आपको इसे स्वयं करना होगा।"

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

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

— एम। डुडले
स्रोत

1

मैं तर्क दूंगा कि क्लीनर कोड दिखाना / उनके कोड को अधिक पठनीय बनाना, कोड में टिप्पणियों के gobs डालने की तुलना में अधिक परिवर्तन दर्शाता है।

— मकोतो

क्या कोई मुझे समझा सकता है कि उन्हें मेरे विचार के बारे में क्या पसंद नहीं है ...?

— एम। डडले

-6

सरल: यदि कर्मचारी टिप्पणी नहीं करता है, तो उसे shift+alt+jकोड दर्ज करने के साथ-साथ प्रत्येक विधि में ऑटो टिप्पणी के लिए प्रेस करने के लिए कहें । कृपया इन समस्याओं से बचने के लिए कोड संशोधन करें।

— पीटर
स्रोत

11

"ऑटो टिप्पणी"? तो यह वह जगह है जहाँ उन सभी "1 से वृद्धि" टिप्पणी से आ रहे हैं? कौन सा आईडीई ऐसा करता है (इसलिए मैं उन नौकरियों से बच सकता हूं जहां इसका उपयोग किया जा रहा है)?

— बजे एक CVn

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

— टीआरजी