XML टिप्पणियों के साथ C#कोड का दस्तावेजीकरण करने के लिए सर्वोत्तम अभ्यास क्या हैं?




code-documentation ndoc (6)

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

सामान्य तौर पर, एक वर्ग और एक विधि के लिए टिप्पणियां लिखते समय कुछ अच्छे दिशानिर्देश क्या हैं? NDoc टिप्पणियों को क्या कहना चाहिए? उन्हें क्या नहीं कहना चाहिए?

मैं अपने आप को देख रहा हूँ कि .NET फ्रेमवर्क टिप्पणियां क्या कह रही हैं, लेकिन यह बहुत जल्दी हो जाता है; अगर मेरे पास खुद को मार्गदर्शन करने के लिए कुछ अच्छे नियम हो सकते हैं, तो मैं अपने डॉक्स को बहुत तेजी से समाप्त कर सकता हूं।


API दस्तावेज़ीकरण बनाने के लिए उपयोग की जाने वाली टिप्पणियों में, आपको निम्न करना चाहिए:

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

  • अपने मापदंडों के लिए सभी पूर्व शर्त सूचीबद्ध करें (शून्य नहीं हो सकते, एक निश्चित सीमा के भीतर होना चाहिए, आदि)

  • किसी भी पोस्टकंडिशन को सूचीबद्ध करें जो प्रभावित कर सकता है कि कॉलर्स रिटर्न मान के साथ कैसे व्यवहार करते हैं।

  • किसी भी अपवाद को सूचीबद्ध करें विधि फेंक सकती है (और किन परिस्थितियों में)।

  • यदि समान विधियाँ मौजूद हैं, तो उनके बीच के अंतरों की व्याख्या करें।

  • किसी भी अप्रत्याशित चीज़ पर ध्यान दें (जैसे कि वैश्विक स्थिति को संशोधित करना)।

  • यदि कोई हो, तो किसी भी दुष्परिणाम को समझें।


एक मान्य XML क्या है यह मत भूलो। उदाहरण के लिए:

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(त्रुटि: अमान्य XML)।


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

/doc साथ कंपाइल करें और कंपाइलर सोर्स कोड में सभी XML टैग्स को सर्च करेगा और XML डॉक्यूमेंट फाइल बनाएगा, फिर Sandcastle जैसे टूल का इस्तेमाल करके फुल डॉक्स जेनरेट करें।


टिप्पणियों के बारे में एक बात उन्हें अद्यतन कर रही है। बहुत से लोग एक फ़ंक्शन को बदल देते हैं फिर परिवर्तन को प्रतिबिंबित करने के लिए टिप्पणी को नहीं बदलते हैं।


StyleCop कोड और टिप्पणी शैली के लिए संकेत प्रदान करता है। इसके द्वारा दिए गए सुझाव MSDN प्रलेखन शैली के अनुरूप हैं।

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


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

उदाहरण के लिए

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... आपने बिल्कुल कोई मूल्य नहीं जोड़ा और बनाए रखने के लिए बस अधिक कोड जोड़ा।

बहुत बार कोड इन शानदार टिप्पणियों से अटे पड़े हैं।





ndoc