एक्सएमएल टिप्पणी करते हुए सुझावों

Question

अच्छा सुबह, दोपहर, शाम या रात (आपके समय क्षेत्र के आधार पर)।

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

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

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

आपकी सलाह और सुझाव, स्कॉट Vercuski के लिए अग्रिम रूप से धन्यवाद

Answer 1

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

भूल वहाँ आप काम आसान टिप्पणी एक्सएमएल बनाने के लिए उपकरण हैं कि नहीं है:

• GhostDoc - विरासत टिप्पणी और templating ऐड-इन।
• Sandcastle Help File Builder - संपादित करता एक जीयूआई के माध्यम से सैंडकैसल परियोजनाओं, एक कमांड लाइन (निर्माण स्वचालन के लिए) से चलाया जा सकता है और कोड से प्राप्त नहीं मदद विषयों के लिए MAML संपादित कर सकते हैं। (1.8.0.0 अल्फा संस्करण बहुत स्थिर और बहुत सुधार हुआ है। इसे लगभग एक महीने के लिए उपयोग कर रहा है, 1.7.0.0 से अधिक)

Answer 2

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

आम तौर पर मैं सभी सार्वजनिक/संरक्षित सदस्यों को सार्थक टिप्पणियां जोड़ने के लिए कड़ी मेहनत करता हूं, जो आसान है, क्योंकि यदि आप निर्माण के दौरान XML टिप्पणियां चालू करते हैं, तो आपको अनुपलब्ध टिप्पणियों के लिए स्वचालित चेतावनियां मिलती हैं। जटिलता के आधार पर, मैं हर विस्तार को भरने सकता है नहीं - यानी अगर यह 100% स्पष्ट क्या हर पैरामीटर है क्या करना है (यानी कोई विशेष तर्क है, और वहाँ केवल 1 चर की व्याख्या की तार्किक तरीका है), तो मैं आलसी हो सकता हूं और पैरामीटर के बारे में टिप्पणी नहीं जोड़ सकता।

लेकिन मैं निश्चित रूप से वर्णन करने के लिए विधियों, प्रकार, गुण, आदि क्या प्रतिनिधित्व करते हैं/कर प्रयास करें।

Answer 3

मैं सार्वजनिक क्लासों और सार्वजनिक/उन वर्गों में से संरक्षित सदस्य दस्तावेज़।

मैं निजी या आंतरिक सदस्यों या आंतरिक कक्षाएं दस्तावेज़ नहीं है। इसलिए चर (मुझे लगता है कि आप फ़ील्ड का मतलब है) क्योंकि वे निजी हैं।

उद्देश्य डेवलपर के लिए कुछ दस्तावेज बनाना है जिसका स्रोत कोड तक पहुंच नहीं है।

कुछ उदाहरण रखने का प्रयास करें जहां उपयोग स्पष्ट नहीं है।

Answer 4

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

इंटेलिसेंस के लिए यह भी बहुत अच्छा है, खासकर नए टीम के सदस्यों के साथ या जैसा कि आपने कहा था, जब मूल लेखक चला गया है।

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

Answer 5

टिप्पणियां अक्सर पुरानी होती हैं। यह हमेशा एक समस्या है। अंगूठे का मेरा नियम: जितना अधिक आपको टिप्पणी को अपडेट करने के लिए काम करने की ज़रूरत है, उतनी तेज़ी से टिप्पणी अप्रचलित हो जाएगी।

एक्सएमएल टिप्पणियां एपीआई विकास के लिए बहुत अच्छी हैं। वे इंटेलिजेंस के साथ बहुत अच्छी तरह से काम करते हैं और वे किसी भी समय HTML सहायता दस्तावेज़ उत्पन्न कर सकते हैं।

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

ठीक है, के बाद से यह बनाए रखने के लिए, गैर निजी प्रतीकों में से एक बहुत कुछ के बाद से महंगा है (गैर एपीआई विकास में) 1 या 2 वर्गों द्वारा केवल उपयोग किया जाता है, और तब से इन symboles अक्सर स्वतः स्पष्ट हैं, मैं लागू कभी नहीं होगा एक नियम कहता है कि प्रत्येक गैर-निजी प्रतीक एक्सएमएल टिप्पणी की जानी चाहिए। यह अधिक मात्रा में और conterproductive होगा। आपको जो कुछ मिलेगा वह मैंने कई जगहों पर देखा है: लगभग खाली एक्सएमएल टिप्पणियां सिंबल नाम में कुछ भी नहीं जोड़ती हैं। और कोड सिर्फ थोड़ा कम पढ़ी जा सकती है कि ...

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

Answer 6

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