.net - कोड प्रलेखन: कितना ज्यादा है?




sandcastle xml-comments (10)

आपके .NET स्रोत में कितना कोड प्रलेखन बहुत अधिक है?

कुछ पृष्ठभूमि: मैंने एक बड़े कोडबेस को विरासत में मिला है जो मैंने उन कुछ अन्य सवालों में किया है जो मैंने यहां पोस्ट किए हैं। इस कोडबेस के "फीचर्स" में से एक में एक ईश्वर क्लास है, जिसमें से एक से एक स्टैटिक क्लास> 3,000 लाइन कोड है जिसमें कई दर्जन स्थिर विधियां शामिल हैं। Utilities.CalculateFYBasedOnMonth() से यह सब कुछ है। Utilities.CalculateFYBasedOnMonth()Utilities.CalculateFYBasedOnMonth() Utilities.GetSharePointUserInfo() लिए। यह सब अच्छा कोड है जिसे फिर से लिखने की ज़रूरत नहीं है , बस एक उपयुक्त सेट लायब्रेरी में पुनर्संचित किया गया है। मैंने योजना बनाई है

चूंकि ये विधियां एक नई व्यावसायिक परत में बढ़ रही हैं, और इस परियोजना पर मेरी भूमिका दूसरे डेवलपर्स द्वारा रखरखाव के लिए सिस्टम तैयार करना है, मैं ठोस कोड दस्तावेज़ीकरण के बारे में सोच रहा हूं। हालांकि इन विधियों में सभी की अच्छी इनलाइन टिप्पणियां हैं, लेकिन XML टिप्पणियों के रूप में वे सभी (या कोई भी) कोड डॉको नहीं करते हैं। GhostDoc और Sandcastle (या दस्तावेज़ X) के कॉम्बो का उपयोग करते हुए, मैं कुछ बहुत अच्छा HTML प्रलेखन बना सकता हूं और इसे SharePoint पर पोस्ट कर सकता हूं, जिससे डेवलपर्स को कोड के माध्यम से नेविगेट किए बिना कोड को और अधिक समझने में मदद मिलेगी।

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

ये उदाहरण दस्तावेज़ एक्स नमूने से हैं :

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

तथा:

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

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

तुम्हे क्या लगता है मैं क्या करूँ?


अपने आप को दोहराना न करें

  • पहला उदाहरण का एक बेहतर तरीका नाम होना चाहिए और कोई भी टिप्पणी नहीं होना चाहिए।
  • दूसरा उदाहरण में कोई टिप्पणी नहीं होनी चाहिए।

पहली विधि का नाम दिखाना चाहिए कि एक नया ऑब्जेक्ट आवंटित किया गया है।

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

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

मुझे यह नहीं देखना है: गिनती नाम की विधि के लिए "गिनती देता है"


आप उन लोगों के बीच एक महत्वपूर्ण विभाजन को मार रहे हैं जो नए पुस्तकालयों को बनाए रखेंगे और जो कि नए पुस्तकालयों का उपभोग करेंगे

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

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


जेफ का टिप्पणी करने के बारे में एक वाकई अच्छा लेख है (या मुझे कहना चाहिए, टिप्पणी नहीं दे रहा है) यहां ...

http://www.codinghorror.com/blog/archives/001150.html

मुझे पता है ऐसा लगता है कि मैं इस सवाल का जवाब नहीं दे रहा हूं, लेकिन मुझे लगता है कि यह एक वैध बिंदु है कि कोड को यथासंभव स्वयं-दस्तावेजी होना चाहिए।


दस्तावेज़ तैयार करने के लिए एक शीर्ष लेख में टिप्पणियाँ एक अच्छी बात है कोड में टिप्पणियां डालकर समझाने के लिए कि आप जो भी कर रहे हैं, वह भी आम तौर पर एक अच्छी बात है। अनावश्यक टिप्पणियों में लगाई गई बातों को संक्षेप में बताएं कि आपने जो किया वह अच्छी बात नहीं है


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

मैंने कभी रेड्डसल की कोशिश नहीं की है, लेकिन मैं एक्सएमएल-टिप्पणी वाले तरीकों के लिए इंटेलिसेंस द्वारा दिए गए आराम की सराहना करता हूं।


मैं हमेशा XML / Javadoc प्रारूप टिप्पणियों का विकल्प चुनता हूं, क्योंकि मुझे एपीआई दस्तावेज को एक समझदार प्रारूप में ब्राउज़ करने में सक्षम होना पसंद है (आमतौर पर HTML)।

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


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

इसलिए कम से कम, महत्वपूर्ण सामग्री को अलग करें या टैगिंग का उपयोग करें (मुझसे पूछें कि क्या आप जावा का उपयोग करते हैं)


वैसे, "क्लीन कोड" (एक महान पुस्तक, बीटीडब्ल्यू) के अनुसार, किसी को HTML / XML मार्कअप का उपयोग टिप्पणियों के भीतर से करना चाहिए जो स्रोत कोड में एम्बेड किए गए हैं। भले ही आपका आईडीई निस्तब्धता प्रलेखन बना सकें, जब आप अपने स्रोतों को ब्राउज़ करते हैं तो यह बहुत ध्यान भंग और अपठनीय माना जाता है।


यह सभी आपकी कंपनी द्वारा उपयोग किए जाने वाले मानकों पर निर्भर करता है, लेकिन मेरे चालक दल के लिए, हम आपके दूसरे उदाहरण की तरह प्रत्येक फ़ंक्शन के शीर्ष पर दस्तावेज़ देते हैं (जिस तरह से आप "/" कुंजी को मारकर दृश्य स्टूडियो 2008 में कर सकते हैं किसी भी उप या समारोह के शीर्ष पर एक पंक्ति में !!)।

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


आपके कोड का उल्लेख किसी को फूला हुआ नहीं करने की आवश्यकता है, XML प्रलेखन किसी अन्य फ़ाइल में हो सकता है:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

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

यह बकवास प्रारूप से अधिक शक्तिशाली है जो कि जावास्काक और डेरिवेटिव है जो आप PHP / Javascript में खोजते हैं (हालांकि जवाडॉक ने XML सिंटैक्स के लिए मार्ग प्रशस्त किया है)। प्लस उपलब्ध उपकरण अब तक बेहतर हैं और सहायता डॉक्स के डिफ़ॉल्ट रूप को और अधिक पठनीय और अनुकूलित करने में आसान है (मैं कह सकता हूं कि लिखने वाले दस्तावेज होने और Sandcastle / DocProject / NDoc को उस प्रक्रिया की तुलना करना)।





ndoc