क्या XML टिप्पणियाँ आवश्यक दस्तावेज हैं?

Question

मैं प्रलेखन के लिए XML टिप्पणियों की आवश्यकता का प्रशंसक हुआ करता था। मैंने दो मुख्य कारणों से अपना विचार बदल दिया है:

1. अच्छे कोड की तरह, तरीके आत्म-व्याख्यात्मक होने चाहिए।
2. व्यवहार में, अधिकांश XML टिप्पणियां बेकार शोर हैं जो कोई अतिरिक्त मूल्य प्रदान नहीं करते हैं।

कई बार हम जेनेरिक टिप्पणियों को उत्पन्न करने के लिए बस घोस्टडॉक का उपयोग करते हैं, और यही मेरा मतलब है कि बेकार शोर से:

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

मेरे लिए, यह स्पष्ट है। यह कहते हुए कि, यदि शामिल करने के लिए विशेष निर्देश थे, तो हमें XML टिप्पणियों का उपयोग करना चाहिए।

मुझे इस लेख का यह अंश पसंद है :

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

क्या मुझे यह सोचना गलत है कि हमें केवल XML टिप्पणियों का उपयोग करना चाहिए, जब कोड स्वयं को समझाने के लिए पर्याप्त नहीं है?

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

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

... और इसे इस में बदल देता है:

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

Comments

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

— लेटी ऑक्ट

@ लेटवेयर: विज़ुअलस्टडियो डिफ़ॉल्ट रूप से इस शैली का समर्थन करता है, कोई अतिरिक्त प्लगइन्स या उपकरण आवश्यक नहीं हैं। इस तरह से उत्पन्न टिप्पणियाँ पॉप-अप टूलटिप्स में तुरंत दिखाई देती हैं।

— FrustratedWithFormsDesigner

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

— लेटी ऑक्ट

Answer 1

यदि आपकी टिप्पणी केवल इस तरह दिखती है:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

फिर हां, वे सभी उपयोगी नहीं हैं। यदि वे इस तरह से कुछ पढ़ते हैं:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

फिर मैं कहूंगा कि उनका मूल्य है। तो आपके प्रश्न का उत्तर देने के लिए: टिप्पणियाँ आवश्यक हैं जब वे कुछ कहते हैं जो कोड नहीं कहता है।

एक अपवाद: किसी भी चीज पर टिप्पणी करना अच्छा है जो सार्वजनिक रूप से सुलभ है यदि आप एक पुस्तकालय / एपीआई लिख रहे हैं जो जनता के लिए उपलब्ध होगा। मैं एक पुस्तकालय का उपयोग करने से घृणा करता हूं और getAPCDGFSocket()एक एपीसीडीजीएफएसकेट का कोई विवरण नहीं होने के कारण एक फ़ंक्शन को देखा है (मैं कुछ के रूप में सरल रूप से खुश हूं This gets the Async Process Coordinator Data Generator File Socket)। तो उस स्थिति में, मैं कहूंगा कि सभी टिप्पणियों को उत्पन्न करने के लिए कुछ टूल का उपयोग करें और फिर मैन्युअल रूप से उन लोगों को ट्विस्ट करें, जिनकी आवश्यकता है (और कृपया सुनिश्चित करें कि आपके क्रिप्टोकरेंसी को समझाया गया है)।

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

... और अंत में, मुझे पूरा यकीन है कि यह सवाल टिप्पणियों की सभी शैलियों के लिए प्रासंगिक है , न कि उन लोगों के लिए जो XML का उपयोग करके स्वरूपित हैं (जो आप उपयोग कर रहे हैं क्योंकि आप एक .NET वातावरण में काम कर रहे हैं)।

Comments

+1 - घोस्टडॉक मेरे लिए पहला संस्करण है, जो बॉयलरप्लेट है, दूसरे संस्करण में, जिसमें दूसरा विस्तृत ज्ञान है।

— जेसी सी। स्लीकर

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

— डैनियल बी

@DanielB या हो सकता है कि आपको टिप्पणियों की आवश्यकता न हो;) मैं इस जवाब के साथ सबसे अधिक अंश के लिए सहमत हूं कि "शब्द आवश्यक है जब वे कुछ कहें, जो कोड नहीं कहता है।" मुझे लगता है कि अगर कोड सब कुछ आवश्यक कहता है, तो आपको टिप्पणियों में अधिक जानकारी की आवश्यकता नहीं है, भले ही टिप्पणियाँ कोड में जानकारी न दें।

— जिमी होफा

.NET में @DanielB - XML ​​टिप्पणियाँ मुख्य रूप से उन स्थितियों के लिए अभिप्रेत हैं जहाँ किसी लाइब्रेरी या सेवा के अंतिम उपयोगकर्ता प्रोग्रामर के पास स्रोत कोड उपलब्ध नहीं है।

— jfrankcarr

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

— jfrankcarr

Answer 2

जो उपयोगकर्ता कोड पढ़ सकते हैं, उनके लिए बेकार दिखने वाली टिप्पणियाँ उन उपयोगकर्ताओं के लिए उपयोगी हो सकती हैं, जिनके पास स्रोत तक पहुँच नहीं है। यह तब होता है जब आपके संगठन के बाहर के लोगों द्वारा बाहरी एपीआई के रूप में कक्षा का उपयोग किया जाता है: आपके XML डॉक्स से उत्पन्न HTML आपके कक्षाओं के बारे में जानने का एकमात्र तरीका है।

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

---

^{* -} किस मामले में uintएक बेहतर विकल्प हो सकता है

Comments

जब आपके पास स्रोत नहीं है तो यह बस नहीं है। यदि आपका संपादक उन्हें पार्स कर सकता है (जैसे विज़ुअल स्टूडियो Xml टिप्पणियां करता है), तो वे माउसओवर / पॉपअप के रूप में आपको एक अलग फ़ाइल पर नेविगेट करने की आवश्यकता के बिना जानकारी दे सकते हैं। जब आप उस फ़ाइल पर जाते हैं जहां सेटर लागू किया जाता है, तो एक 1 लाइन रेंज वैधीटर जो एक इंट्रस्ट को एक संकीर्ण सीमा तक सीमित करता है, स्पष्ट है; लेकिन जब आप "myFrobable.Fro ..." टाइप करना शुरू करते हैं तो "फ्रोबेबलाइड 0 और 1000 के बीच होना चाहिए" दिखाई देता है और ऑटोकंप्लीट हमारे लिए एक सहायक रिमाइंडर है।

— दान

Answer 3

आप इस तरह की बेकार टिप्पणियों से बचने के बारे में बिल्कुल सही हैं। वे कोड को पढ़ना आसान बनाने के बजाय अधिक कठिन बनाते हैं, और बहुत अधिक स्थान ले रहे हैं।

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

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

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

BTW आप अपने पुराने कोड पर लौटकर टिप्पणी लिखने की अपनी क्षमता में सुधार कर सकते हैं और इसे समझने की कोशिश कर सकते हैं (आप 2-3 महीनों में अपना कोड भी नहीं पहचान सकते हैं _ यह बिल्कुल किसी और के कोड को पढ़ने की तरह है)। यदि आप यह दर्द रहित रूप से करते हैं, तो सब कुछ ठीक है।

Comments

मैं किसी को भी नहीं जानता जो गेटर्स / सेटर्स पर कमेंट लिखने का प्रयास करता है। यदि आप लगभग किसी भी आधुनिक आईडीई का उपयोग कर रहे हैं (और यहां तक ​​कि उन्नत पाठ संपादक प्लगइन्स के माध्यम से इसका समर्थन कर सकते हैं), गेटर्स और सेटर को आमतौर पर माउस-क्लिक या दो, या राइट कीस्ट्रोक (यदि यह कॉन्फ़िगर किया गया है) के साथ बहुत आसानी से प्रलेखित किया जा सकता है। जब आप डेटाबेस स्कीमा या WSDL के आधार पर कोड उत्पन्न करते हैं तो कभी-कभी वे स्वचालित रूप से उत्पन्न हो जाते हैं ...

— FrustratedWithFormsDesigner

@FrustratedWithFormsDesigner, जिस व्यक्ति के बारे में मैं बात कर रहा था वह कंपनी छोड़ने वाला था, और मेरा मानना ​​है कि गेटर्स / सेटर पर उन सभी टिप्पणियों को उस व्यक्ति द्वारा यह दिखाने के लिए किया गया था कि उसने कुछ दस्तावेज छोड़ने के लिए कुछ प्रयास किया था

— सुपर मॉक्ट

व्यक्ति द्वारा नोटिस दिए जाने के बाद सभी बोगो टिप्पणी दर्ज की गई थी? मैंने देखा है कि लोग जगह-जगह खाली / बेकार xml टिप्पणियाँ बना रहे हैं। वी.एस.

— डैन इज़

@ डान नीली, मुझे लगता है कि उस व्यक्ति ने वास्तव में परवाह नहीं की और केवल टिप्पणियों को जोड़ने के लिए कहा कि टिप्पणियां जोड़ी जाती हैं। हम आमतौर पर टिप्पणियों पर ज्यादा ध्यान नहीं देते हैं, लेकिन अगर किसी को छोड़ना है और एक घटक पर काम कर रहा है, तो उसे स्पष्ट पठनीय कोड लिखना होगा।

— सुपरएम