संबंधित कोड से पहले या बाद में टिप्पणी [बंद]

Question

यह मानते हुए कि जिस लाइन पर यह लागू होता है उस पर एक टिप्पणी फिट नहीं होगी (या नहीं जा सकती), क्या किसी को कोड से पहले या बाद में टिप्पणी लिखनी चाहिए?

खैर, जहां भी भविष्य के पाठक टिप्पणी के दायरे को अच्छी तरह से समझेंगे। दूसरे शब्दों में, जहाँ भी अधिकांश प्रोग्रामर / स्क्रिप्टर्स ऐसी टिप्पणी करते हैं।

इसलिए अधिकांश प्रोग्रामर / स्क्रिप्टर्स एक टिप्पणी कहां रखते हैं: इसके कोड से पहले या बाद में?

यदि आपका उत्तर केवल विशिष्ट भाषाओं पर लागू होता है, तो कृपया संकेत दें कि कौन सा है।

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

Comments

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

— deadalnix

@deadalnix, धन्यवाद, यह दीपन मेहता के जवाब के रूप में अच्छी तरह से समझा जाता है। (इस प्रकार अब तक सभी उत्तरदाताओं के लिए धन्यवाद, और प्रत्येक के लिए +1।)

— msh210

Answer 1

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

Microsoft का कहना है कि एक छोटी सी टिप्पणी के साथ प्रक्रिया शुरू करने के लिए यह एक अच्छा प्रोग्रामिंग अभ्यास होगा। (वे प्रक्रियाओं के बाद टिप्पणी करने का उल्लेख नहीं करते हैं) MSDN लिंक VisualBasic के बारे में है, लेकिन यह उन सबसे प्रोग्रामिंग भाषाओं पर लागू होता है जो मुझे लगता है।

Comments

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

— msh210

@ msh210: तो आप अन्य अच्छे प्रोग्रामर की व्यक्तिगत प्राथमिकताओं के लिए Microsoft प्राथमिकता पसंद करते हैं? लेकिन क्या आप जानते हैं कि कैसे Microsoft ने हंगेरियन नोटेशन को एक मानक के रूप में गलत पाया? हाँ? क्या आप? केवल सामान्य ज्ञान पर भरोसा करें, हमेशा भीड़ के साथ न चलें या सबसे बड़े बैल का पालन करें।

— फाल्कन

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

— msh210

Answer 2

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

Answer 3

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

Answer 4

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

कारण, जब कोई इसे पढ़ना शुरू करता है, तो यह स्पष्ट प्रश्न बन जाता है कि कुछ इस तरह से क्यों किया जाता है; जहां तक ​​व्यक्ति को यह पता नहीं होता कि उत्तर के लिए स्क्रॉल करने के लिए किस बिंदु की आवश्यकता है। यदि यह शीर्ष पर है, तो यह देखना सही है।

Answer 5

इसलिए अधिकांश प्रोग्रामर / स्क्रिप्टर्स एक टिप्पणी कहां रखते हैं: इसके कोड से पहले या बाद में?

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

एकमात्र अपवाद जिसके बारे में मैं सोच सकता हूं, वह इस तरह से पहले की गई टिप्पणी अनुभाग के अंत को चिह्नित करने वाली टिप्पणी है:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

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

Answer 6

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

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

// this workaround is required to make the compiler happy
int i = 0;

बनाम

int i = 0; // make the compiler happy

लेकिन कभी नही:

int i = 0;
// this workaround is required to make the compiler happy

Comments

प्रश्न को फिर से पढ़ें: यह निर्दिष्ट करता है कि यह एक अलग लाइन पर एक टिप्पणी के बारे में पूछ रहा है।

— msh210 0

@ msh210 यह एक सही जवाब है। "पहले टिप्पणियां लिखें"। यह और भी अधिक विस्तृत है और एक संभावित कारण बताएं कि आपको क्यों लगता है कि वे "जब वे छोटे होते हैं और लाइन के अंत में होते हैं" को छोड़कर।

— आरडीएस

Answer 7

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

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

यह वास्तव में आपके प्रश्न की ढोंग और वैधता की उपेक्षा है, क्योंकि आपके पास उस प्रश्न के उत्तर के विपरीत है। मुझे अभी भी लगता है कि यह प्रासंगिक है और आपकी मदद कर सकता है, और मैं एक झटका नहीं था। यदि नहीं, तो -1 की मुझ पर हावी होगी।

Comments

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

— एड स्टब

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

— आरडीएस

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

— नकली नाम

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

— एड स्टब

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

— फेक नेम

Answer 8

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

Answer 9

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

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

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

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Comments

आपके दोनों कोड ब्लॉक में टिप्पणी करने से पहले वे कोड हैं।

— msh210 0

आपकी खुद की टिप्पणियों ने आपके "मामले के बाद" हीहे :) को गले लगा लिया और इसे क्रिसमस का थीम बनाने के लिए गले लगा लिया और उदाहरण के लिए

— अहमद मसूद

@ msh210 मैं अपनी टिप्पणियों को पहले उदाहरण में देख रहा हूँ अगर (क्रिसमस) परीक्षा में टिप्पणी करते हुए, निम्नलिखित कार्यों के बारे में "" के रूप में नहीं किया जा रहा है (अर्थात, वे कह रहे हैं "इसका क्या मतलब है कि हम यहाँ हैं?") वे पहले से कहते हैं एक कोड ब्लॉक, लेकिन मैंने कभी ऐसा कोड नहीं देखा है जो ... कोड (); कोड (); / * टिप्पणी पूर्ववर्ती ब्लॉक * /} की व्याख्या करते हुए और इस तरह से सवाल नहीं उठाया

— लैरी ओब्रायन ने

Answer 10

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

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

इस संबंध के बाद, यह उस कोड के ब्लॉक के ऊपर टिप्पणी डालने के लिए अधिक उपयुक्त लगता है जिसे वह संदर्भित करता है।

Answer 11

एक टिप्पणी को कोड के एक टुकड़े के ऊपर या नीचे जाने की आवश्यकता हो सकती है, यह किस प्रकार की टिप्पणी पर निर्भर करता है: यदि यह कोड क्या करता है की एक अल्ट्रा-संक्षिप्त विवरण देता है, तो उसे कोड को पूर्ववर्ती करने की आवश्यकता होती है; यदि यह कोड के काम करने के तरीके के बारे में तकनीकी विवरण को स्पष्ट करता है, तो उसे कोड का पालन करने की आवश्यकता है।

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

[blank line]
/* comment */
{ code }
[blank line]

आप जानते हैं कि टिप्पणी कोड से संबंधित है, और यह बताता है कि कोड क्या करता है। जबकि, यदि आप निम्नलिखित देखें:

[blank line]
{ code }
/* comment */
[blank line]

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

Comments

जैसा कि मैं हमेशा कहता हूं: बिना स्पष्टीकरण के आपका पतन मुझे एक बेहतर व्यक्ति बनने में मदद नहीं करता है। मैं भी तुमसे प्यार करता हूं!

— माइक नाकिस

Answer 12

ऊपर टिप्पणियाँ सबसे अच्छा है।

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

कोड "स्व दस्तावेज" हो सकता है (और होना चाहिए), लेकिन अगर आपको यह समझने के लिए कोड की हर पंक्ति को पढ़ना और समझना है कि एक विधि कैसे काम करती है। If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

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

मैं SO थ्रेड से भी सहमत हूं - क्या हमें पहले के बजाय कोड ब्लॉक के बाद टिप्पणियां जोड़नी चाहिए? ..

मैं भी सामने जानता था ...

Answer 13

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

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

एक अतिरिक्त लाभ यह है कि जब कठिन हो जाता है मैं लॉग ट्रेसिंग चालू कर सकता हूं और अधिक विस्तृत निष्पादन लॉग प्राप्त कर सकता हूं।