जावाडोक टिप्पणियां बनाम ब्लॉक टिप्पणियां?

Question

विधियों की शुरुआत में ब्लॉक टिप्पणी का उपयोग करना उचित कब है, और जब जावाड-स्टाइल टिप्पणी का उपयोग करना उचित होता है? कार्यान्वयन टिप्पणियों और प्रलेखन टिप्पणियाँ:

जावा कार्यक्रमों टिप्पणियों के दो प्रकार के हो सकते हैं:

Java style guide के "टिप्पणी" अनुभाग से, मैं इस पाया। कार्यान्वयन टिप्पणियां सी ++ में मिली हैं, जो /*...*/, और // द्वारा सीमित हैं। दस्तावेज़ीकरण टिप्पणियां ("डॉक्टर टिप्पणियां" के रूप में जाना जाता है) केवल जावा हैं, और /**...*/ द्वारा सीमित हैं। डॉक्टर टिप्पणियां को javadoc टूल का उपयोग करके HTML फ़ाइलों में निकाला जा सकता है।

कार्यान्वयन टिप्पणियां कोड के लिए टिप्पणी या टिप्पणियों के लिए के लिए विशेष कार्यान्वयन के बारे में हैं। दस्तावेज़ टिप्पणियां को कार्यान्वयन-मुक्त परिप्रेक्ष्य से कोड के विनिर्देशन का वर्णन करने के लिए हैं। डेवलपर्स द्वारा पढ़ा जा सकता है जो पर हाथ पर स्रोत कोड आवश्यक नहीं है।

तो, वाक्यांश को दूसरी तरह से मेरे सवाल होगा: जब तरीकों, कोड का एक विनिर्देश लायक है एक कार्यान्वयन से मुक्त परिप्रेक्ष्य (जावाडोक) के बजाय एक विशेष कार्यान्वयन के बारे में एक टिप्पणी, और इसके विपरीत से? क्या एक इंटरफ़ेस javadoc टिप्पणियां प्राप्त करेगा, जबकि कार्यान्वयन ब्लॉक टिप्पणियां प्राप्त करेंगे?

संपादित करें: मुझे लगता है कि मैं अब तक अपने प्रश्नों को सही तरीके से संदेश नहीं दे रहा हूं।

यहां एक उदाहरण है जो मैं जानना चाहता हूं।

/** 
* Javadoc comment here about general implementation? 
*/ 
/* 
* Should I now have a separate block comment for my specific implementation? 
*/ 
public void foo() 
{ 
... 
} 

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

भी पूछने के लिए प्रेरणा है कि ग्रहण मेरे लिए यह स्वत: जनरेट अभी है:

/* 
* (non-Javadoc) 
* @see my.package#process() 
*/ 

और मैं लगा आपकी प्रतिक्रिया विशिष्टताओं में विशेष रूप से घोषित नहीं किया गया है स्टाइल यहाँ पर जा के कुछ प्रकार है मैं ऊपर से लिंक।

Answer 1

जानकारी कक्षा के उपयोगकर्ता को पता होना चाहिए कि जवाडोक टिप्पणी में जाना चाहिए।

जानकारी एक वर्ग को संशोधित करने वाला डेवलपर सामान्य टिप्पणी (ब्लॉक या रेखा) में जाने की आवश्यकता है।

और यह कोड (वर्ग, इंटरफ़ेस, क्षेत्र, विधि, निर्माता, ...) के किसी भी ब्लॉक दोनों एक जावाडोक टिप्पणी और एक सामान्य टिप्पणी ब्लॉक, हो सकता है कि बहुत संभव है जब दोनों सार्वजनिक रूप से दिखाई और साथ ही आंतरिक दस्तावेज की आवश्यकता है।

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

Answer 2

मेरी राय में, जावाडोक टिप्पणियां टिप्पणियां हैं जो आप लोगों को लिखते हैं जो आपके कोड का उपयोग करते हैं, और जो आपके तरीकों का आह्वान करते हैं।

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

ब्लॉक टिप्पणियां आंतरिक टिप्पणियां हैं, टिप्पणियां जो आप अपना कोड बनाए रखने वाले लोगों के लिए लिखते हैं।

ब्लॉक टिप्पणियां यह समझने के लिए महत्वपूर्ण हैं कि कोड कैसे काम करता है, यह क्यों काम करता है और कौन सा ऑपरेशन वास्तविक कार्य करने के लिए उपयोग किया जाता है।

Answer 3

मेरी राय में विधि के शीर्ष पर ब्लॉक टिप्पणियां डालने का कोई मतलब नहीं है (ठीक है, कभी भी कम से कम कभी नहीं कहें)। इंटरफ़ेस विधियों पर जावाडोक टिप्पणियां अनुबंध को निर्दिष्ट करती हैं, कक्षा के तरीकों पर वे कार्यान्वयन के बारे में बताते हैं ताकि उपयोगकर्ता एक वर्ग का उपयोग कर सकें यदि एक से अधिक इंटरफेस को लागू करने वाले कई वर्ग हैं। List इंटरफ़ेस के बारे में सोचें; कार्यान्वयन ArrayList और LinkedList विभिन्न उपयोग मामलों में उपयुक्त हैं, इसलिए उनके संबंधित दस्तावेज उनके पेशेवरों और विपक्ष के बारे में बता सकते हैं।

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

ग्रहण की स्वचालित रूप से जेनरेट की गई ब्लॉक टिप्पणियां आपके लिए भरने के लिए हैं और संभावित रूप से उन्हें लापता तारांकन जोड़कर जावाडोक टिप्पणियां बनाने के लिए हैं। मैं बिल्कुल नहीं जानता कि वे किस मामले में दिखाई देते हैं लेकिन एक ऐसा होता है जब आप किसी मौजूदा वर्ग से इंटरफ़ेस निकालते हैं। फिर कक्षा से जावाडोक इंटरफेस विधि पर जाता है और कक्षा विधि ब्लॉक टिप्पणी प्राप्त करता है। इसके पीछे तर्क यह है कि अक्सर एक इंटरफ़ेस को लागू करते समय आपके पास वास्तव में जोड़ने के लिए बहुत कुछ नहीं होता है। फिर मैं उदाहरण के रूप में List का उपयोग करता हूं। size() विधि को ArrayList और LinkedList कार्यान्वयन में और अधिक दस्तावेज़ीकरण की आवश्यकता नहीं होगी। उनके पास जोड़ने के लिए कुछ भी मूल्य नहीं है। बेशक यह उदाहरण दूषित है क्योंकि वास्तविक कार्यान्वयन (कम से कम ओपनजेडीके) में जावाडॉक्स हैं लेकिन मुझे इसकी कोई आवश्यकता नहीं है और वास्तव में मूल्य के कुछ भी नहीं जोड़ते हैं। इससे भी बदतर वे इंटरफेस दस्तावेज की तुलना में कम जानकारी प्रदान करते हैं।