/// टिप्पणी ब्लॉक महत्वपूर्ण क्यों हैं?

Question

किसी ने एक बार कहा था कि हमें अपने सभी तरीकों को /// <summary>टिप्पणी ब्लॉक (C #) के साथ उपसर्ग करना चाहिए लेकिन यह नहीं बताया कि क्यों।

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

क्या /// <summary>आपके कोड में टिप्पणी ब्लॉक का उपयोग करने का कोई अच्छा कारण है ?

मैं आम तौर पर //हर समय टिप्पणियों का उपयोग करता हूं , यह सिर्फ उन /// <summary>ब्लॉकों को है जिनके बारे में मैं सोच रहा था।

Comments

मुझे यकीन नहीं था कि अगर ये टिप्पणी ब्लॉक व्यक्तिगत पसंद या अनुशंसित मानक थे

— राहेल

मुझे भी लगता है कि एस.ओ.

— रयान हेस

मुझे लगता है कि यह ठीक उसी तरह का सवाल है जो यहाँ है। एक अच्छा मौका है कि यह व्यक्तिपरक होने के नाते स्टैकओवरफ्लो पर बंद हो जाएगा।

— पैड्सक्लेकर

यदि आप प्रलेखन उत्पन्न करना चाहते हैं तो <सारांश> ब्लॉकों का उपयोग करें। यदि आप दूसरों के उपयोग के लिए एपीआई बना रहे हैं तो यह समझ में आएगा। हर विधि के लिए ऐसा करना ओवरकिल है और आपके लचीलेपन को कम करता है।

— मैक्नील

Answer 1

इनका ज्यादा से ज्यादा इस्तेमाल करें।

हां, वे विशेष टिप्पणियां हैं जो विधि के लिए दस्तावेज बन जाती हैं। की सामग्री <summary>, पैरामीटर टैग आदि, जो उत्पन्न होते हैं, जब आप या किसी और को आपकी विधि को कॉल करने के लिए तैयार हो रहे हैं, तो यह इंटेलीजेंस में दिखाई देता है। वे अनिवार्य रूप से आपकी पद्धति या वर्ग के लिए सभी दस्तावेज देख सकते हैं बिना फाइल में जाने के लिए यह पता लगाने के लिए कि यह क्या करता है (या केवल विधि हस्ताक्षर और सर्वश्रेष्ठ के लिए आशा पढ़ने की कोशिश करें)।

Comments

+1 बिल्कुल उनका उपयोग करें। आपको आश्चर्य होगा कि यदि आपके घटकों का पुन: उपयोग किया जाता है और यह सब महान प्रलेखन में उपलब्ध है, तो आपके लिए यह कितना उपयोगी है।

— वाल्टर

इसके अलावा अगर आप विजुअल स्टूडियो का उपयोग कर रहे हैं और किसी क्लास, मेथड या फील्ड डिक्लेरेशन से ठीक पहले /// के साथ एक लाइन शुरू करते हैं, तो वीएस आपके लिए एक्सएमएल डॉक्यूमेंटेशन स्ट्रक्चर तैयार करेगा - आपको बस इसे भरना होगा। मैं मानता हूं कि इसे पूरा करना है। आपकी स्क्रीन का बहुत अधिक स्थान है, लेकिन यह एक योग्य समझौता है जो मैं कहूंगा। इसके अलावा, एफ # के पास इसके लिए कुछ बेहतर समर्थन हैं (जैसे कि आपको <सारांश> और </ सारांश> का उपयोग करने की आवश्यकता नहीं है क्योंकि वे 'मान्य' हैं)।

— ShdNx

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

— ज्येल्टन

बस एक बात जोड़ने के लिए, इन टिप्पणियों को dll में संकलित नहीं किया गया है, आपको अपने dll के साथ संबंधित xml फ़ाइल वितरित करनी होगी।

— बेंजोल

वे उपयोगी हैं, लेकिन वे वर्तमान वर्ग को बहुत ही अपठनीय बनाते हैं। काश कोई और तरीका होता जो कोड को अव्यवस्थित नहीं करता।

— जीरोन वैन लैंगेन

Answer 2

हां, आप जो कुछ भी रखना चाहते हैं, उसके लिए इनका पूरी तरह से उपयोग करें, या साझा किया जा सकता है।

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

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

आम तौर पर हालांकि मैं सिर्फ एक .chm फ़ाइल का उत्पादन करता हूं, जिसे आसानी से साझा किया जाता है।

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

Comments

ब्लॉग का लिंक मृत प्रतीत होता है (अंतिम पोस्ट 5 साल पहले पूरे पृष्ठ पर टूटे हुए HTML के साथ), और परियोजना का स्थान बदल गया है। क्या आपके पास सैंडकास्टल के लिए एक अद्यतन लिंक है?

Answer 3

यदि आपका कोडिंग मानक मांग करता है कि आप ऐसी टिप्पणियों का उपयोग करते हैं (और एपीआई या फ्रेमवर्क के लिए एक कोडिंग मानक इसकी मांग कर सकता है), तो आपके पास कोई विकल्प नहीं है, आपको ऐसी टिप्पणियों का उपयोग करना होगा।

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

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

सेवा

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

सेवा

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Comments

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

— मैट डिटरोलियो

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

— वैभव

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

— अज़ेगलोव

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

— अज़ेगलोव

@JYelton आपके विधि नाम के साथ समस्या यह नहीं है कि यह वर्णनात्मक है, बल्कि यह कम से कम 2 अलग-अलग ऑपरेशनों का वर्णन करता है और इसलिए इसे कम से कम 2 स्वतंत्र तरीकों में फिर से सक्रिय किया जाना चाहिए।

— नील

Answer 4

आपकी कक्षा, पद्धति, और संपत्ति का नामकरण स्वयं स्पष्ट होना चाहिए, इसलिए यदि आपको इनकी आवश्यकता है, तो यह संभवतः एक गंध है।

हालाँकि, मैं किसी भी सार्वजनिक कक्षाओं, विधियों, और संपत्तियों पर API, लाइब्रेरी, आदि में उनका उपयोग करने की सलाह दूंगा ... बहुत कम से कम, वे डॉक्स को आपके देव का उपयोग करने में मदद करने के लिए उत्पन्न करेंगे, और आपको होने से रोकेंगे। उन्हें लिखने के लिए।

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

Comments

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

— एडम लेअर

हां, मैं मान लूंगा कि आपके पास एक बिंदु है, लेकिन अधिकांश समय पैरामीटर की कमी स्पष्ट है कि वे नहीं हैं?

— जॉन मैकइंटायर सेप

यकीन नहीं होता कि मैं जॉन से सहमत हूं। इस तर्क के साथ, .net फ्रेमवर्क विधियों में से किसी को भी किसी भी Intellisense की सहायता नहीं मिलनी चाहिए।

— वैभव

@ वैभव - मैंने कहा "मैं उन्हें किसी भी सार्वजनिक वर्ग, विधियों, और संपत्तियों पर एपीआई, पुस्तकालय, आदि ... में उपयोग करने की सलाह दूंगा ..." ... जो आप के बारे में बात कर रहे हैं वह इसे कवर नहीं करेगा?

— जॉन मैकइंटायर

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

— वैभव

Answer 5

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

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

Answer 6

हां, मैंने उन्हें बनाया है। [खरोंच से नए सिस्टम का निर्माण करते समय]

नहीं, मुझे उनसे कभी कोई फायदा नहीं हुआ। [मौजूदा सिस्टम पर काम करते समय जिन्हें रखरखाव की आवश्यकता होती है]

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

Comments

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

— rjzii

Answer 7

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

यह आपके कोड को दस्तावेज़ करने के लिए सबसे अधिक दिखाई देने वाले तरीकों में से एक है।

इनलाइन डॉक्यूमेंट को पढ़ने के लिए सोर्स कोड ढूंढना या एक डॉक्यूमेंट को खोदना एक दर्द है जो कोड में होता है। यदि आप बुद्धि के माध्यम से कुछ उपयोगी पॉप अप कर सकते हैं तो लोग आपसे प्यार करेंगे।

Answer 8

" यह मेरी तरह बहुत इस्तेमाल किया जाना है;) "

मैं टिप्पणियों (///) के साथ खेलता था। एक वर्ग के लिए आप बस इस तरह की टिप्पणी कर सकते हैं

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

लेकिन, एक विधि के लिए आप मापदंडों और रिटर्न प्रकारों के लिए विवरण देने के साथ और अधिक जोड़ सकते हैं।

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

आप इस टिप्पणी को बनाने के लिए एक शॉर्ट-कट का उपयोग कर सकते हैं (///+Tab)।

Answer 9

पुस्तकालयों को छोड़कर उनका उपयोग करना

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

लेकिन वर्तमान परियोजना के आंतरिक लोगों के लिए, वे बस रास्ते में आते हैं।

Answer 10

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

Answer 11

मैं VB में बराबर का उपयोग करता हूं (क्योंकि वे मुझे C # का उपयोग नहीं करने देंगे - जाहिर है यह बहुत कठिन है ... कोई टिप्पणी नहीं।) मैं उन्हें बहुत सुविधाजनक लगता हूं। अधिकांश समय मैं प्रतीक्षा करता हूं जब तक कि प्रक्रिया या फ़ंक्शन उन्हें डालने से पहले बहुत पूरा नहीं हो जाता है, यदि केवल टिप्पणियों को बदलने से बचने के लिए - या उन्हें "सिंक से बाहर" किया जाए।

मैं जरूरी नहीं कि एक उपन्यास लिखूं - बस मूल बातें, पैरामीटर विवरण और कुछ टिप्पणी (आमतौर पर जब वहाँ "सामान्य से बाहर कुछ" चल रहा है - वर्कअराउंड या अन्य बकवास है कि मैं वहाँ नहीं है, लेकिन है कोई विकल्प "अभी के लिए"।) (हाँ, मुझे पता है, कि "अभी के लिए" पिछले साल हो सकता है।)

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