गुण के XML प्रलेखन में "हो जाता है या सेट .." आवश्यक है?

19

मैं C # में XML टिप्पणियों के लिए एक सर्वोत्तम अभ्यास की सिफारिश की तलाश कर रहा हूं। जब आप कोई प्रॉपर्टी बनाते हैं, तो ऐसा लगता है कि अपेक्षित XML दस्तावेज़ीकरण के निम्नलिखित रूप हैं:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

लेकिन चूंकि संपत्ति के हस्ताक्षर पहले से ही आपको बताते हैं कि वर्ग के बाहरी ग्राहकों के लिए कौन से संचालन उपलब्ध हैं (इस मामले में यह दोनों है getऔर set) मुझे ऐसा लगता है कि टिप्पणी बहुत गंदी है और शायद निम्नलिखित पर्याप्त होंगे:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft पहले फॉर्म का उपयोग करता है इसलिए ऐसा लगता है कि यह एक निहित सम्मेलन है। लेकिन मुझे लगता है कि मेरे द्वारा बताए गए कारणों में से दूसरा बेहतर है।

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

मैं आधिकारिक अनुशंसित प्रथाओं के किसी भी विचार या लिंक की सराहना करूंगा।

c# .net programming-practices comments

— टॉमस
स्रोत

ईमानदारी से केवल एक चीज मुझे टिप्पणी देती है जो कोड में नहीं है (यह मानते हुए कि यह उपयोगकर्ता का सदस्य है) यह है कि आईडी अद्वितीय है। इसलिए इसमें से कोई भी 'आवश्यक' नहीं है।

— जे.के.

@ टॉमास - क्या आपने घोस्टडॉक प्लगइन स्थापित किया है ? यदि आप शुरू करने के लिए अच्छी संपत्ति के नामों का उपयोग करते हैं और संपत्ति एक्सेसरों के आधार पर gets or setsया स्वचालित रूप से डालते हैं तो यह आपके लिए अच्छी XML टिप्पणियाँ उत्पन्न करेगा gets।

— ट्रेवर पिली

@ ट्रेवर - मेरे पास यह स्थापित है। मैं बस सोच रहा था कि क्या मुझे इसके टेम्पलेट बदलने चाहिए और "गेट्स या सेट्स" को हटा देना चाहिए या नहीं :)। यह एक महान प्लगइन है, हालांकि।

— टॉमस

अविवेक की दुनिया में आपका स्वागत है ।

— कर्नल पैनिक

28

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

इस वर्ग को उदाहरण के लिए लें:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

जब इन गुणों में से किसी एक को एक्सेस करने के लिए इन्टेलिसेन्स को खींच लिया जाता है, तो कोई संकेत नहीं होता है कि किन लोगों को लिखा जा सकता है, इससे पढ़ा जा सकता है, या दोनों:

यहाँ छवि विवरण दर्ज करें

इसी तरह जब हम दस्तावेज भी देखते हैं तो हम निश्चित नहीं होते हैं:

यहाँ छवि विवरण दर्ज करें

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

यहाँ छवि विवरण दर्ज करें

— माइक
स्रोत

गहन उत्तर के लिए धन्यवाद। मुझे लगता है कि ये दुर्भाग्य से Visual Studio IDE की सीमाएँ हैं। मैंने इसके बारे में सोचा है और मुझे लगता है कि इंटेलीजेंस आपको दिखा सकता है कि कौन से गुण हैं, उदाहरण के लिए, getवर्तमान संदर्भ में। किसी विशेष विकास के माहौल को फिट करने के लिए प्रलेखन को मोड़ना बहुत सुविधाजनक नहीं है। फिर भी मुझे लगता है कि Visual Studio और C # इतने निकट से संबंधित हैं कि यह सही समाधान हो सकता है।

— टॉमस

1

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

— माइक

2

स्टाइलकॉपGets or Sets ... नोटेशन का उपयोग करता है जो इसे नियम 1616 के साथ लागू करता है ।

लिंक किया गया पृष्ठ एक और मामला सूचीबद्ध करता है जिसे आपने सूचीबद्ध नहीं किया है:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

आपके द्वारा सूचीबद्ध दूसरा विकल्प होगा।

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

बनाम

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

जो इंटैलिसेंस संकेत पर जानकारी नहीं देगा कि संपत्ति केवल पढ़ी जाती है, आप इस मामले के लिए एक सम्मेलन भी कर सकते हैं, लेकिन Gets ..., Gets or Sets...क्या यह काम अच्छी तरह से करता है।

स्टाइलकॉप नियम पर सूचीबद्ध अन्य संस्करण भी हैं जो उपयोग करके स्पष्ट हैं, Gets or Sets...लेकिन बिना नहीं हो सकते हैं।

इसके अलावा जब Doxygen या Sandcastle जैसी किसी चीज से डॉक्यूमेंटेशन तैयार किया जाता है, तो पूरा नोटेशन API (उदाहरण के लिए) को बेहतर तरीके से डॉक्यूमेंट करेगा।

— NikolaiDante
स्रोत

2

XML टिप्पणियों में किसी संपत्ति के प्राप्त करने और स्थापित करने के बारे में जानकारी जोड़ने का एकमात्र समय यह है जब यह अपेक्षित रूप से व्यवहार नहीं करता है (सीधे सार्वजनिक प्राप्त करें और सेट करें)।

यदि या तो निजी हैं या यदि उनके पास अतिरिक्त तर्क हैं, तो मैं उनका उल्लेख करता हूं, अन्यथा मैं संपत्ति के इरादे का दस्तावेजीकरण करता हूं।

— CLandry
स्रोत

1

मैं और अधिक वर्बोज़ संस्करण के साथ खुश हूँ।

दूसरा "वृद्धि काउंटर" की टिप्पणी के बाद की तरह है, ठीक है, एक काउंटर चर बढ़ाना।

यह स्पष्ट है कि एक गेट और सेट है। यदि आपके पास एक निजी सेटर है, तो यह स्पष्ट होगा क्योंकि आपके पास निजी कीवर्ड होगा।

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

— ozz
स्रोत