टिप्पणियों में तनातनी से कैसे निपटें? [बन्द है]

Question

कभी-कभी मैं खुद को ऐसी स्थितियों में पाता हूं जब मैं जो कोड लिख रहा हूं (या लगता है ) इतना आत्म-स्पष्ट है कि इसका नाम मूल रूप से एक टिप्पणी के रूप में दोहराया जाएगा:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(C # उदाहरण, लेकिन कृपया प्रश्न को भाषा-अज्ञेय के रूप में देखें)।

उस तरह की टिप्पणी बेकार है; मैं क्या गलत कर रहा हूं? क्या यह उस नाम का विकल्प है जो गलत है? मैं इस तरह के हिस्सों को बेहतर कैसे कह सकता हूं? क्या मुझे इस तरह की चीजों के लिए टिप्पणी को छोड़ देना चाहिए?

Comments

नोट: मैं "अपडेट का स्थान" बहुत अस्पष्ट होने पर विचार करूंगा जब तक कि यह स्पष्ट न हो कि "अपडेट" क्या है। क्या सिस्टम URI की तुलना में अन्य प्रकार का समर्थन करता है?

return result # returns result

— लुकास स्टैस्कल

टिप्पणियों में tautology से निपटने का तरीका टिप्पणियों में tautology से निपटने का तरीका है। (यह एक टिप्पणी है।)

— रेक्स केर

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

— कोडी ग्रे

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

— केविन मैककॉर्मिक

Answer 1

मैं जिन परियोजनाओं पर काम करता हूं, उनमें प्रत्येक एकल वर्ग के सदस्य पर विस्तृत टिप्पणी लिखने के लिए पर्याप्त समय नहीं है।

इसका मतलब यह नहीं है कि टिप्पणियों के लिए समय नहीं है; इसके विपरीत, वहाँ बहुत समय हो गया है कि tautological टिप्पणियों के लिए जो कुछ भी टिप्पणी की जा रही है के एक rephrased संस्करण वापस puke। वे एक प्रारंभिक बिंदु के रूप में महान काम करते हैं ।

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

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

और फिर जैसा कि आप कोड जारी रखते हैं, जब आप यह याद नहीं रख सकते हैं UpdateLocationकि अपडेट किस स्थान पर हुआ था, या जिस स्थान पर अपडेट भेजा जा रहा है, आपको कोड को फिर से भेजना होगा। यह इस बिंदु पर है कि आपको उस अतिरिक्त जानकारी को जोड़ना चाहिए:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

यदि कभी कोई अन्य प्रोग्रामर आपसे किसी क्षेत्र के विवरण के बारे में पूछता है, तो उस जानकारी के साथ टिप्पणियों को अपडेट करें:

Example.UpdateLocationस्टोर करने के लिए किस प्रकार के अपडेट का उपयोग किया जाना चाहिए ?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

और प्रोग्रामिंग की तरह, आपकी टिप्पणियों को कहीं शुरू करना होगा। टॉटोलॉजिकल कॉमेंट्स कॉमेंट्स हैं Hello World!, जैसे-जैसे आप लेखन और प्रलेखीकरण का अभ्यास करते हैं, आपके शुरुआती डॉक्यूमेंट अधिक से अधिक लचीले होते जाएंगे।

Comments

वास्तव में वैकल्पिक टिप्पणी देने वाले एकमात्र व्यक्ति होने के लिए +1; बल्कि सिर्फ तनातनी के जवाबों के साथ।

— इयान बॉयड

यह वास्तव में अब तक का सबसे अच्छा जवाब है।

— रोलैंड टेप

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

— रोलैंड टेप

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

— zzzzBov

Answer 2

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

मैं एक प्रेरणा के लिए साक्षर प्रोग्रामिंग अभ्यास पर एक नज़र डालने की सलाह दूंगा।

Comments

+1 - यही जवाब है! हमें "डिक्लेयर वैरिएबल", "

— इन्क्रीमेंट

इसलिए ओपी के उदाहरण में, एक अच्छी टिप्पणी क्या होगी?

— टिजिन

@stijn, मुझे नहीं पता - यह (जाहिर है) कोड से गायब है। कुछ ऐसा जो केवल कोड के लेखक को इसके उद्देश्य और सीमाओं के बारे में पता हो।

— SK-लॉजिक

शायद कुछ टिप्पणी जैसे // अपडेट बढ़ाता है LevelOfAttack (URL के रूप में उत्तीर्ण) के अनुसार

— woliveirajr

सबसे महत्वपूर्ण सवाल एक टिप्पणी का जवाब देना चाहिए " डब्ल्यूटीएफ? "

— n

Answer 3

टिप्पणियों को कोड का वर्णन करना चाहिए , इसे डुप्लिकेट नहीं करना चाहिए । यह हेडर टिप्पणी केवल डुप्लिकेट करता है। इसे छोड़ दो।

Comments

+1: मुझे लगता है कि मुझे समझ में आ गया है कि आपका क्या मतलब है, लेकिन मैं इस बात से सहमत नहीं हूं कि आपने कहा है :-) जहाँ तक संभव हो, कोड को कोड का वर्णन करना चाहिए, जबकि टिप्पणियों को आपके तर्क का वर्णन करना चाहिए।

— क्रामिनी ने मोनिका

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

— एसके-लॉजिक

@ एसके-तर्क: मैं असहमत हूं। एक लंबी विधि एक छोटी विधि की तुलना में कम आत्म-वर्णन है जो अच्छी तरह से नामित सबरूटीन्स की एक श्रृंखला को बुलाती है।

— क्रामिनी ने मोनिका

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

— SK-लॉजिक

@ एसके-लॉजिक, क्रैमि क्या कहता है: "कोड को पढ़ने और समझने में आसान होना चाहिए" और वे सभी रेखांकन आदि जिनका आप उल्लेख कर रहे हैं, जो वह कहते हैं, में गिरता है: "टिप्पणियों को आपके तर्क का वर्णन करना चाहिए"

— शहबाज़

Answer 4

उन्हें छोड़ दो!

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

उन्हें अंदर रखो!

आपका उदाहरण इस नियम के दो अपवादों को दर्शाता है:

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

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

Comments

यह सबसे अच्छा जवाब है। आपको यह पता लगाने में सक्षम होना चाहिए कि जब आप उदाहरण वर्ग का उपभोग कर रहे हैं और संपत्ति पर होवर करते हैं, तो संपत्ति का क्या उपयोग किया जाएगा।

— एंडी

इन स्थितियों मैं प्रयास करते हैं (और अक्सर असफल) में, कम से कम या तो जोड़ने के लिए <remarks/>या <see/>तो कुछ अतिरिक्त सामग्री उपलब्ध कराने के। <summary/>अभी भी दोहराया गया है, लेकिन टिप्पणी समग्र पूरी तरह से बेकार नहीं है।

— इयरलैमलेस

Answer 5

मैं "टिप्पणियों को नहीं लिखता" प्रतिक्रियाओं से दृढ़ता से असहमत हूं। क्यों? मुझे अपने उदाहरण को थोड़ा बदलकर इंगित करें।

public Uri UpdateLocation ();

तो यह कार्य क्या करता है:

• क्या यह "अपडेट लोकेशन" लौटाता है? या
• क्या यह स्थान को "अपडेट" करता है और नया स्थान लौटाता है?

आप देख सकते हैं कि टिप्पणी के बिना अस्पष्टता है। एक नवागंतुक आसानी से गलती कर सकता है।

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

Comments

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

— ozz

Uri UpdateLocation()कोड समीक्षा द्वारा अस्वीकार कर दिया जाएगा और इसे Uri GetUpdateLocation()या तो बदल दिया जाएगा void UpdateLocation()।

— अवकर

@avakar: भावना के साथ सहमत हैं, लेकिन जैसा कि यह एक सी # संपत्ति है (प्राप्त करें और सेट स्वचालित रूप से संश्लेषित होते हैं और एक ही नाम है) का नाम बदलकर GetUpdateLocationकोड जैसा होगा GetUpdateLocation = somelocation। LocationOfUpdateएक बेहतर नाम होगा, जो अस्पष्टता को दूर करता है। मूल समस्या यह है कि ओपी एक संज्ञा के बजाय एक क्रिया उपसर्ग का उपयोग करता है। एक विधि की कार्रवाई को इंगित करने के लिए अग्रणी क्रियाओं को माना जाता है।

— एंट

@DPD, "एक पंक्ति को चलाने में कितना समय और प्रयास लगता है" इसे बनाए रखने में कितना प्रयास लगता है? यह कितना स्क्रीन एस्टेट बर्बाद करता है? यह कितना समय बर्बाद करता है जब यह अंततः कोड के साथ सिंक से बाहर निकल जाता है और डेवलपर्स को भ्रमित करना शुरू कर देता है?

— अवकर

विधि एक मान लौटाती है, और एक क्रिया-वाक्यांश नाम होता है। यही समस्या है। इसमें संज्ञा-वाक्यांश नाम होना चाहिए। जैसे O उरी स्थानऑफयूडेट ()। GetUpdateLocation नहीं, क्या आप कहते हैं "आपका गेटलोकेशन क्या है?"

— ctrl-alt-delor

Answer 6

/// <summary>ब्लॉक का उपयोग IntelliSense और API दस्तावेज़ीकरण के लिए दस्तावेज़ बनाने के लिए किया जाता है ।

इस प्रकार, यदि यह एक सार्वजनिक-सामना करने वाला एपीआई है, तो आपको हमेशा कम से कम एक <summary>टिप्पणी शामिल करनी चाहिए , भले ही फ़ंक्शन का उद्देश्य पाठकों के लिए स्व-स्पष्ट होना चाहिए ।

हालाँकि, यह नियम का अपवाद है; सामान्य तौर पर, बस DRY (अपने आप को दोहराएं) को याद रखें ।

Answer 7

टिप्पणियों को इस तरह भरें कि यदि आप जानते हैं कि आप उस तरह से कैसे लाभान्वित होंगे; अन्यथा बस उन्हें मिटा दें।

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

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

इस विशेष उदाहरण के लिए, मैं "स्व-वर्णनात्मक प्रकार" का उपयोग करूँगा (यह मानते हुए कि ऐसा नहीं है जहाँ काम खत्म हो जाएगा), जैसे:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

Answer 8

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

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

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

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

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

लब्बोलुआब यह है: भविष्य के बारे में सोचो। अपने आप से पूछें कि आपके लिए यह महत्वपूर्ण और स्पष्ट है कि कार्यक्रम को भविष्य में कैसे समझा और संशोधित किया जाना चाहिए। [१]

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

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

---

[१] यह टिप्पणियों के मुद्दे से परे है, लेकिन इसे लाने लायक है: यदि आप पाते हैं कि आपको इस बात का बहुत कुरकुरा विचार है कि आपका कोड भविष्य में कैसे बदल सकता है, तो आपको संभवतः केवल एक टिप्पणी करने से परे सोचना चाहिए और उन मापदंडों को एम्बेड करना चाहिए। कोड के भीतर ही, क्योंकि यह लगभग हमेशा एक और अधिक विश्वसनीय तरीका होगा ताकि आप अपने कोड के भविष्य के संस्करणों की विश्वसनीयता सुनिश्चित करने की तुलना में किसी अज्ञात भविष्य के व्यक्ति को सही दिशा में ले जाने के लिए टिप्पणियों का उपयोग करने की कोशिश कर सकें। एक ही समय में आप भी overgeneralizing से बचना चाहते हैं, क्योंकि मनुष्य भविष्य की भविष्यवाणी करने में कुख्यात हैं, और इसमें प्रोग्राम परिवर्तन का भविष्य भी शामिल है। इसलिए, कार्यक्रम के डिजाइन के सभी स्तरों पर भविष्य के उचित और अच्छी तरह से सिद्ध आयामों को परिभाषित करने और पकड़ने की कोशिश करें, लेकिन डॉन '

Answer 9

अपने स्वयं के कोड में, मैं अक्सर टिप्पणी के स्थान पर टिप्पणी छोड़ दूंगा, जिसमें विशेष रूप से अहंकारी जैसे:

<?php
// return the result
return $result;
?>

... जो स्पष्ट रूप से एक व्याख्यात्मक दृष्टिकोण से कोड को अधिक समझदार बनाने के संदर्भ में बहुत कम योगदान देता है।

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

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

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(अधूरे कोड, एसक्यूएल इंजेक्शन आदि को नजरअंदाज करें। आप विचार प्राप्त करें।)

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

Comments

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

— क्रिस एलन लेन

मैंने आपके लिए सिंटैक्स हाइलाइटिंग भाषा संकेत जोड़े ।

— पाओलो एबरमन

Answer 10

निम्न में से एक करने के लिए टिप्पणियों का उपयोग किया जाना चाहिए।

1. दस्तावेज़ जनरेटर के लिए सूचना हड़पने के लिए। यह समझा नहीं जा सकता, यह अत्यंत महत्वपूर्ण है।
2. क्यों कोड का एक टुकड़ा है जिस तरह से यह चेतावनी है, और क्या अन्य विचार। मैंने 2 प्रोग्रामिंग भाषाओं में लिखे कोड से निपटा है। इसका एक महत्वपूर्ण हिस्सा दो भाषाओं के बीच एक सामान्य संरचना होना था। दोनों स्थानों पर एक टिप्पणी उपयोगकर्ता को सूचित करती है कि यदि वे इस संख्या को बदलते हैं, तो उन्हें दूसरे को बदलने की भी आवश्यकता होती है।
3. विशेष रूप से अजीब दिखने वाला कोड क्यों है, यह समझाने के लिए नोट्स लिखें। यदि आपको यह सोचना है कि किसी विशेष तरीके से काम करने के लिए कोड का एक टुकड़ा कैसे प्राप्त करें, और समाधान शुरू से ही स्पष्ट नहीं है, तो यह संभवतः एक स्पष्टीकरण के लायक है कि आप क्या करने की कोशिश कर रहे थे।
4. यदि वे स्पष्ट नहीं हैं, तो इनपुट / आउटपुट लेबल करना। यह जानना हमेशा अच्छा होता है कि आपके इनपुट क्या होने की उम्मीद है, और वे किस प्रारूप में हैं।

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

1. उन चीजों को समझाएं जो बेहद स्पष्ट हैं। मैंने एक बार इस तरह से विरासत कोड देखा page=0; // Sets the page to 0:। मुझे लगता है कि कोई भी सक्षम व्यक्ति यह पता लगा सकता है।

Answer 11

मैं टॉटोलॉजी को हटा दूंगा लेकिन टिप्पणी रखूंगा, मैं नमूना मूल्य देकर गुणों और चर नामों पर टिप्पणी करूंगा, ताकि उपयोग को स्पष्ट रूप से समझा जा सके:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

अब मुझे पता है कि वास्तव में वहाँ क्या जाता है, और टिप्पणी से, मुझे स्पष्ट विचार है कि इसका उपयोग कैसे करना है।

Answer 12

मैं कहूंगा कि यह टिप्पणियों के उद्देश्य पर निर्भर करता है।

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

यदि टिप्पणी कुछ भौगोलिक रूप से दूर की टीम के लिए प्रलेखन उत्पन्न करेगी, तो मैं हर बिट प्रलेखन को वहां रखूंगा।

Answer 13

मुझे लगता है कि इस विषय पर "टिप्पणियों: विरोधी पैटर्न" जैसे नामों के तहत काफी चर्चा की गई है, या "टिप्पणी एक कोड गंध है?" ( एक उदाहरण )।

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

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

Answer 14

यदि आप कोड लिख सकते हैं जिसमें टिप्पणियों की आवश्यकता नहीं है तो आपने प्रोग्रामिंग निर्वाण प्राप्त किया है!

कम टिप्पणियाँ आपके कोड बेहतर कोड की आवश्यकता है!

Comments

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

— SK-Logic

शायद "हैलो वर्ल्ड!" प्रोग्रामर निर्वाण है तो ...

— naught101

: -} - यह कुछ ऐसा है जो बहुत कम ही प्राप्त होता है - बिंदु यह है कि यदि आपका संघर्ष एक टिप्पणी खोजने के लिए संघर्ष करता है जो अर्थ जोड़ता है तो बस अपने आप से प्रसन्न रहें इसका मतलब है कि आपका कोड बस सही है!

— जेम्स एंडरसन

Answer 15

उस तरह की टिप्पणी बेकार है; मैं क्या गलत कर रहा हूं?

यह केवल बेकार लगता है यदि आप पहले से ही जानते हैं कि क्या UpdateLocationकरता है। क्या "अद्यतन" यहाँ एक क्रिया या एक संज्ञा है? यही है, क्या यह कुछ ऐसा है जो स्थान को अपडेट करता है, या क्या यह अपडेट का स्थान है? इस तथ्य से उत्तरार्द्ध का अनुमान लगाया जा सकता है कि UpdateLocationयह स्पष्ट रूप से एक संपत्ति है, लेकिन बड़ा मुद्दा यह है कि कभी-कभी यह स्पष्ट रूप से कुछ ऐसा करने के लिए चोट नहीं पहुंचाता है जो स्पष्ट लगता है।

Answer 16

ऑटो-संकलित दस्तावेज़ीकरण एक तरफ, कोड को स्वयं दस्तावेज़ करना चाहिए, ताकि टिप्पणियों में केवल दस्तावेज़ होना चाहिए जहां कोड स्वयं दस्तावेज़ करने के लिए पर्याप्त नहीं है।

Answer 17

"स्थान" एक तरह का स्पष्ट है, लेकिन "अपडेट" थोड़ा अस्पष्ट हो सकता है। यदि आप एक बेहतर नाम नहीं लिख सकते हैं, तो क्या आप टिप्पणी में अधिक विवरण दे सकते हैं? क्या अद्यतन करें? हमें यह क्यों चाहिये? कुछ धारणाएं क्या हैं (शून्य स्वीकार्य है)?