स्व दस्तावेज़ कोड बनाम। टिप्पणी कोड

Question

मेरे पास एक खोज थी, लेकिन मुझे वह नहीं मिला, जिसकी मुझे तलाश थी, कृपया मुझे लिंक करने के लिए स्वतंत्र महसूस करें यदि यह प्रश्न पहले से ही पूछा जा रहा है।

इस महीने की शुरुआत में यह पद बनाया गया था:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

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

दिए गए उदाहरण में

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

लेखक ने कहा कि इस कोड को एक टिप्पणी दी जानी चाहिए, मेरी निजी राय है कि कोड एक फ़ंक्शन कॉल होना चाहिए जो वर्णनात्मक है:

$extension = GetFileExtension($image_filename);

हालांकि टिप्पणियों में किसी ने वास्तव में सिर्फ यह सुझाव दिया:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

लेखक ने टिप्पणी करते हुए कहा कि "उन लोगों में से एक था", यानी एक बुरा प्रोग्रामर।

प्रत्येक व्यक्ति स्वयं वर्णन कोड बनाम टिप्पणी कोड पर क्या विचार रखता है?

Comments

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

— फिल

मुझे वह लेख .... पढ़ने में भयानक लग रहा है। बहुत अपमानजनक।

— sevenseacat

@ कर्क - क्या मैंने किया :(

— फिल

"आप एक बुरे PHP प्रोग्रामर क्यों हैं" उत्तर: क्योंकि आप PHP में प्रोग्रामिंग कर रहे हैं।

— थॉमस ईडिंग

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

— dallin

Answer 1

मैं स्वयं दस्तावेज कोड लिखना पसंद करता हूं। इसके लिए एक गाइड है क्लीन कोड ।

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

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

Comments

मुझे वह किताब बहुत पसंद है :)

— Phill

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

— मैथ्यू एम।

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

— डोभाल

@Doval: एक दिलचस्प दर्शन, कम से कम क्या कोड के बारे में टिप्पणी के संबंध में करता है । दूसरी ओर, कुछ सबसे उपयोगी टिप्पणियां हो सकती हैं कि कोड कुछ क्यों नहीं करता है - एक अवधारणा जो मुझे नहीं लगता कि कोड को व्यक्त करने की उम्मीद की जानी चाहिए।

— सुपरकैट

पूरी तरह असहमत। नामकरण की कोई भी राशि तर्क के उद्देश्य का पूरी तरह से वर्णन करने वाली नहीं है।

— कोलोब कैनियन

Answer 2

आपको यह नहीं बताना चाहिए कि कोड क्या कर रहा है, लेकिन आपको यह दस्तावेज़ करना चाहिए कि वह ऐसा क्यों कर रहा है।

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

अन्य सभी टिप्पणियों से सुरक्षित रूप से छुटकारा पाया जा सकता है।

Comments

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

— डेविड मिस्टर

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

— ट्राईलैक्स

@ ट्रिक्क्स कुछ मामलों के लिए काम करता है लेकिन सभी के लिए नहीं। इस परिदृश्य की कल्पना करें for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place:। अब, यह न तो ऐसा कुछ है जो कि एन्क्लोजिंग फ़ंक्शन के उद्देश्य से स्पष्ट है, और न ही इसे अपने स्वयं के फ़ंक्शन में फैक्टर किया जा सकता है। यदि आप इसे अधूरा छोड़ देते हैं, तो यह स्पष्ट रूप से बुरा है। तो आप अपने इरादे को स्पष्ट करने के लिए एक टिप्पणी जोड़ें।

— बिज़िकलॉप

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

— बिज़लीकॉप

Answer 3

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

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

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

Comments

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

— पावर्सेलेव

पुनश्च, मुझे पता है कि मैं 'zombied' थोड़े हूँ :) इसके लिए क्षमा करें

— Powerslave

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

— पोवर्सलेव

Answer 4

सौभाग्य से, इस चर्चा के दोनों शिविरों का यहां प्रतिनिधित्व किया गया है, और दोनों के लिए समर्थक और कांग्रेस तर्क का उल्लेख किया गया था।

मेरा मानना ​​है कि दोनों शिविरों में अतिव्यापी तर्क हैं, और वास्तव में उनमें से अधिकांश पर सहमत हैं, जिस तरह से उन्हें प्राप्त करने का तरीका थोड़ा अलग है।

ओवरलैपिंग तर्क

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

अब, मुख्य अंतर यह है कि उन तर्कों में से कुछ पर कितना वजन डाला जाता है।

आत्म-वर्णन कोड

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

अधिक टिप्पणियाँ

• टिप्पणियाँ कोड की तुलना में अधिक पठनीय हैं। प्लेन इंग्लिश कुछ का वर्णन करने में बेहतर है।

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

मेरा मानना ​​है कि दोनों शिविरों में बहुत ही मान्य तर्क हैं, लेकिन आपको एक शिविर का पालन नहीं करना चाहिए, क्योंकि यह एक मुद्दे को हल करता है।

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

दूसरी ओर, आप अक्सर एपीआई को देखते हैं जहां हर फ़ंक्शन पर टिप्पणी की जाती है, सिर्फ इसलिए कि 'टिप्पणियां अच्छी हैं'। जिन चीजों पर टिप्पणी की जानी चाहिए वे अभी भी नहीं हैं।

Comments

@Steven - "दूसरी ओर, आप अक्सर एपीआई को देखते हैं जहां हर फ़ंक्शन पर टिप्पणी की जाती है, सिर्फ इसलिए कि 'टिप्पणियां अच्छी हैं'। जिन चीजों पर टिप्पणी की जानी चाहिए थी, वे अभी भी नहीं हैं।" ऊ, इतना निराशाजनक सच है!

— dss539

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

— पावलेव

Answer 5

"मुझे माफ करना, लेकिन आपका लड़का।"

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

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

एक चरम शैली के रूप में साक्षर प्रोग्रामिंग को देखें।

Comments

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

— पीटर एलेनवेब

Answer 6

लघु, बेहतर और सही उत्तर

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

टिप्पणियों की तुलना में बहुत बेहतर उत्तर का उपयोग केवल यह बताने के लिए किया जाना चाहिए कि "क्यों" वह टिप्पणी है:

• "क्यों" (निश्चित रूप से) की व्याख्या करें
• अलग-अलग लाइनों पर "क्या" केवल तभी समझाएं जब कोड जटिल हो या उद्देश्य अस्पष्ट हो और यह आगे सरलीकृत करने के लायक नहीं हो सकता है या नहीं हो सकता है
• समझ को बढ़ाने के लिए कोड के ब्लॉक के लिए "क्या" समझाएं और आपको क्या चाहिए

यह वापस करने के लिए स्पष्टीकरण

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

उदाहरण के लिए, अगर मैं किसी और के फ़ंक्शन को देख रहा हूं, तो क्या यह कोड के माध्यम से लाइन से लाइन पर जाना आसान है, यह देखने के लिए कि फ़ंक्शन क्या कर रहा है या फ़ंक्शन में तीन अच्छी तरह से लिखी गई टिप्पणियों को देखने के लिए कि फ़ंक्शन क्या कर रहा है और कहां है यह कर रहा है?

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

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

Comments

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

— dallin

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

— मैगस

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

— 18

but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forइसे "विधि / कार्य का नाम" कहा जाता है। यदि आपको कोड का एक ब्लॉक मिला है जिसका कोई नाम नहीं है, लेकिन यह इतना लंबा है कि आप इसे एक त्वरित नज़र में नहीं ले सकते हैं, तो शायद समस्या वहीं है।

— बिजिकलोप

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

— dallin

Answer 7

वैसे आपको कुछ ऐसा भी याद रखना होगा जो आपके लिए स्पष्ट या "स्व-दस्तावेजीकरण" हो, किसी और के लिए नहीं हो सकता है ... हो सकता है कि किसी के पास कुछ कार्यों की कम समझ हो। इसलिए मैं हर चीज के बारे में टिप्पणी करता हूं।

Comments

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

— फिल

+1 यह आपके दर्शकों के लिए एक सवाल है। इस फ़ंक्शन का उपयोग करने की संभावना कौन है? आप उनकी मदद कैसे कर सकते हैं? आपकी मदद के लायक क्या होगा? क्या टिप्पणी जोड़ने के लिए अभी थोड़ा समय खर्च करने से अधिक है? आदि आदि। आदि

— पीटरएलेबब

@PeterAllenWebb: उस टिप्पणी का कोई मतलब नहीं है। इसका मतलब यह नहीं है कि फ़ंक्शन को टिप्पणी नहीं की जानी चाहिए; यह होना चाहिए। "एक्सटेंशन" में डॉट शामिल है या नहीं? के लिए वापसी मूल्य क्या है "foo"? ( null? "") के लिए "foo."? nullएक अपवाद के कारण गुजर जाएगा, या फ़ंक्शन कुछ (शायद null) वापस करेगा ?

— टीजे क्राउडर

Answer 8

ठीक है, स्व दस्तावेज कोड के साथ बात यह है कि उस फ़ंक्शन के भीतर, आप पाएंगे:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

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

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

Comments

हाँ। मुझे लगता है कि आपको यह सोचने के लिए "प्रशिक्षित" होना चाहिए कि यह एक या दूसरे होना चाहिए और दोनों नहीं।

— पीटरअलेनवेब

Answer 9

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

Comments

यह मानते हुए कि सब कुछ के लिए एक कारण है, यह टिप्पणी की जानी चाहिए?

— 14

हाँ, ठीक है। इसलिए मेरा मानना ​​है कि अपने कोड को कमेंट करने का सबसे अच्छा तरीका एक साक्षर प्रोग्रामिंग है।

— तर्क

Answer 10

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

$ एक्सटेंशन = GetFileExtension ($ image_name);

आपकी छूट पर वापस जाने के लिए, क्या मैं इसके लिए छवि नामों की एक सरणी भेज सकता हूं, या क्या यह केवल एक छवि लेता है? क्या यह किसी भी प्रकार की फ़ाइल का समर्थन करता है, या उनमें से कुछ ही? क्या यह मेरे लिए स्ट्रिंग को सुरक्षित करेगा, या मुझे इसे करना होगा? यदि फ़ाइल प्रकार मौजूद नहीं है, तो क्या यह मुझे सूचित करता है?

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

Comments

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

— मैट एलेन

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

— डोनल फैलो

शायद उदाहरण इस प्रश्न में उपयोग करने के लिए एक बुरा था, मैंने लगभग 7 वर्षों में PHP को नहीं छुआ है, सी # और जावा का एक छोटा सा कर रहा है, इसलिए मुझे एक आईडीई का उपयोग करने की आदत है जो मुझे बताती है कि प्रकार वापस आ गया है या प्रकारों की घोषणा करना।

— फिल

@ डॉनल फेलो: इसे फाइल, एकवचन कहते हैं। उस बारे में क्या अस्पष्ट है? यह पूरी तरह से स्पष्ट है।

— मैट एलेन

तथ्य यह है कि स्पष्टता पर चर्चा करने वाले 4 लोगों की अब 7 प्रतिक्रियाएं हैं या अन्यथा एक ही फ़ंक्शन कॉल से मुझे पता चलता है कि आपको टिप्पणियों का उपयोग करने की आवश्यकता है । इस तथ्य पर भी प्रकाश डाला गया है कि सटीक नामकरण अपने आप में एक कला है।

— चींटी

Answer 11

एक दूसरे को बाहर नहीं करता है। भले ही आपका कोड स्व-टिप्पणी है, लेकिन कई बार आपको यह बताने के लिए नियमित टिप्पणियों की आवश्यकता हो सकती है कि आपका आत्म-टिप्पणी कोड ऐसा क्यों करता है।

Comments

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

— फिल

कोड कभी भी इसके उद्देश्य की व्याख्या नहीं कर सकता है । जब आप एक हथौड़ा देखते हैं, तो आप यह पता नहीं लगा सकते हैं कि यह क्या है - यह खोपड़ी को गलाने के लिए है या सिर्फ एक कच्चा लोहा बनाने के लिए है।

— एसके-तर्क

@ एसके-तर्क:public <T> void hit(T item);

— माइकल के

@ मिचेल - बिल्कुल। उपयोगकर्ता यह कैसे पता लगाएगा कि किस श्रेणी की वस्तुओं को अंकित किया जा सकता है? एक बहुत बेहतर प्रकार की प्रणाली के साथ भी यह हमेशा स्पष्ट नहीं होता है कि किसी डेवलपर द्वारा संभावित उपयोग की किस श्रेणी की योजना बनाई गई है।

— तर्क

Answer 12

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

बस चालाक होने की कोशिश न करें क्योंकि चतुर कोड भयानक है और बनाए रखा है। कीवर्ड: रखरखाव !

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

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

Answer 13

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

जब आपका ऐप किसी विशेष डोमेन के लिए होता है, तो हर किसी को सहमत होने और / या एक सामान्य शब्दावली स्थापित करने में शामिल करना मुश्किल हो सकता है। हमें संक्षिप्ताक्षर और व्यापक शब्दजाल से बचने के लिए सिखाया जाता है, लेकिन मैं इसे कॉल करने जा रहा हूं

EBITDA

और नहीं

EquityBeforeInterestTaxesDepreciationAndAmortization

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

Answer 14

मुझे लगता है कि हमें प्रलेखन और के बीच अंतर करने की आवश्यकता है expressivity कोड की।

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

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

Answer 15

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

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Answer 16

मैं आमतौर पर सेल्फ-डॉक्यूमेंटिंग कोड लिखने का पक्ष लेता हूं, जहां टिप्पणी अस्पष्ट है, क्योंकि मुझे लगता है कि अधिकांश कोड पूरी तरह से खुद दस्तावेज नहीं होंगे।

Answer 17

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

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

IMO: स्व-दस्तावेजीकरण कोड वह कोड है जहां चर और विधि के नाम सार्थक और प्रासंगिक नाम दिए जाते हैं, ताकि वे यह बताएं कि उनका उद्देश्य क्या है।

Answer 18

यदि आपने अपने कोड को कई बार संशोधित किया है और अभी भी डोमेन को जानने वाले किसी व्यक्ति को इरादा स्पष्ट करने का कोई तरीका नहीं मिला है। फ़ंक्शन को फिर से लिखें। आखिरकार यह 10-20 लाइनों से अधिक नहीं है। यदि यह लंबे समय तक फ़ंक्शन को फिर से लिखता है, तो यह लंबे समय तक है और इसका कारण यह है कि यह अपठनीय है :) कुल्ला-दोहराना

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

सीधे शब्दों में कहें कि आप टिप्पणी नहीं कर रहे हैं उन्हें कोड

Answer 19

कोड पूरा द्वितीय संस्करण देखें, पृष्ठ 128-129।

सार डेटा प्रकार आपको इस पहेली से बचाएंगे। सेल्फ डॉक्यूमेंटिंग कोड जाने का तरीका है। टिप्पणियाँ उपयोगी हो सकती हैं, लेकिन होने में

निम्न-स्तरीय कार्यान्वयन के बजाय वास्तविक-विश्व इकाइयाँ

आप टिप्पणियों का उपयोग करने से बचने में सक्षम हैं।

टिप्पणियों के बारे में एक बात यह है कि आप उन्हें एक बार लिखते हैं, लेकिन जब आप फ़ंक्शन को कार्यान्वित करते हैं तो आप उन्हें नहीं देखते हैं, आप केवल उन्हें देखते हैं जब आप फ़ंक्शन को बदलते हैं।

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

Answer 20

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

Answer 21

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

यदि आप इसे ध्यान में रखते हैं, जब कोडिंग / प्रोग्रामिंग?

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

अपनी नौकरी के अधिकांश समय में, मुझे हमेशा अन्य लोगों के कोड को संशोधित करना पड़ा, और सबसे बुरी तरह से लिखा गया, खराब दस्तावेज।

तो कोड डॉक्यूमेंट के स्वंय को सोचने की आपकी आदत, सिर्फ परिश्रम नहीं कर रही है।

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

Http://thedailywtf.com देखें कि उनके पास प्रोग्रामर के बारे में बहुत सारी हास्यप्रद लेकिन वास्तविक कहानियां हैं, जिन्होंने सिर्फ उनके कारण का तनुकरण नहीं किया।