क्या जावदोक टिप्पणियों को कार्यान्वयन में जोड़ा जाना चाहिए?

Question

क्या इंटरफ़ेस में जावदोक टिप्पणियों को जोड़ना और कार्यान्वयन में गैर-जावदोक टिप्पणियाँ जोड़ना सही है?

जब आप ऑटो कमेंट करते हैं, तो ज्यादातर IDE कार्यान्वयन के लिए गैर-जावाडॉक टिप्पणियां उत्पन्न करते हैं। क्या ठोस विधि का वर्णन नहीं होना चाहिए?

Answer 1

उन तरीकों के लिए जो केवल लागू हो रहे हैं (ओवरराइड नहीं), निश्चित रूप से, क्यों नहीं, खासकर अगर वे सार्वजनिक हैं।

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

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

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

Comments

क्या आपको पहले से पता नहीं है कि ट्री-मैप का उपयोग करते समय तत्वों की तुलना करने की आवश्यकता होती है? एक कार्यान्वयन भी परस्पर विरोधी व्यवहार को लागू नहीं करना चाहिए।

— जिमी टी।

मुझे लगता है कि यह सही उत्तर होना चाहिए stackoverflow.com/a/39981265/419516

— user219882

Answer 2

कार्यान्वयन और इंटरफ़ेस दोनों में javadoc होना चाहिए। कुछ उपकरणों के साथ, आप इंटरफ़ेस के प्रलेखन को @inheritDoc कीवर्ड के साथ विरासत में दे सकते हैं।

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

Comments

वास्तव में 'कुछ उपकरण' क्या हैं? क्या यह बॉक्स से बाहर काम करता है या यह कुछ विशिष्ट प्लगइन्स के लिए बाध्य है।

— jediz

मुझे पता है कि ग्रहण उपयोग करता है {@inheritDoc}और यह केवल तभी काम करता है जब आपके पास@Override पहले एनोटेशन न हो

— ksnortum

Answer 3

थोड़ा अच्छा अभ्यास करना है

/**
 * {@inheritDoc}
 */

कार्यान्वयन के javadoc के रूप में (जब तक कि कुछ अतिरिक्त कार्यान्वयन के विवरण के बारे में समझाया न जाए)।

Comments

इंटरफ़ेस होने की बात यह है कि इस विधि को कई तरीकों से लागू किया जा सकता है। अगर मैं केवल टिप्पणियों को विरासत में लेने जा रहा हूं, तो कार्यान्वयन में टिप्पणी होने का क्या मतलब है?

— वैशाख सुरेश

मैं उपरोक्त टैग का उपयोग करता हूं और फिर टैग के नीचे कोई भी अतिरिक्त आवश्यक दस्तावेज रखता हूं।

— बेन पेज

Answer 4

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

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

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

---

निश्चित रूप से विपरीत मामला हो सकता है, जब आप वास्तव में ओवरराइडिंग विधि में एक टिप्पणी जोड़ना चाहते हैं (आमतौर पर कुछ अतिरिक्त कार्यान्वयन विवरण या अनुबंध को थोड़ा सख्त करना)। लेकिन इस मामले में, आप लगभग कभी ऐसा कुछ नहीं करना चाहते:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

क्यों? क्योंकि विरासत में मिली टिप्पणी संभवतः बहुत लंबी हो सकती है। ऐसे मामले में, 3 लंबे पैराग्राफ के अंत में अतिरिक्त वाक्य को कौन नोटिस करेगा ?? इसके बजाय, बस अपनी टिप्पणी के टुकड़े को लिखें और यह सब है। सभी javadoc टूल हमेशा लिंक द्वारा किसी प्रकार का निर्दिष्ट करते हैं, जिसे आप बेस क्लास टिप्पणी पढ़ने के लिए क्लिक कर सकते हैं। उन्हें मिलाने का कोई मतलब नहीं है।

Answer 5

@ यह इंटरफ़ेस में विवरण के लिए एक लिंक बनाता है। लेकिन मुझे लगता है कि कार्यान्वयन के बारे में कुछ विवरण जोड़ना अच्छा है।

Comments

@seeइंटरफ़ेस विधियों को जोड़ने के लिए IMO एक अच्छा अभ्यास है और यह ज्यादातर मामलों में पर्याप्त है। जब आप javadoc को इंटरफ़ेस विधि से ठोस क्रियान्वयन में कॉपी करते हैं तो आप केवल डुप्लिकेट जानकारी की नकल करते हैं और यह जल्दी से असंगत हो सकता है। हालांकि, कार्यान्वयन के बारे में किसी भी अतिरिक्त जानकारी को javadoc में जोड़ा जाना चाहिए।

— पायोत्र

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

— 21

Answer 6

Sjoerd सही ढंग से कहता है कि इंटरफ़ेस और कार्यान्वयन दोनों में JavaDoc होना चाहिए। इंटरफ़ेस JavaDoc को विधि के अनुबंध को परिभाषित करना चाहिए - विधि को क्या करना चाहिए, यह क्या इनपुट लेता है, इसे किन मूल्यों पर वापस लौटना चाहिए और त्रुटि के मामलों में इसे क्या करना चाहिए।

कार्यान्वयन प्रलेखन को अनुबंध पर एक्सटेंशन या प्रतिबंधों को ध्यान में रखना चाहिए, और कार्यान्वयन का उपयुक्त विवरण, विशेष रूप से प्रदर्शन।

Answer 7

उत्पन्न javadoc के लिए हाँ यह मायने रखता है। यदि आप केवल इंटरफ़ेस का उपयोग करके एक ठोस कार्यान्वयन के संदर्भ की घोषणा करते हैं तो यह नहीं है क्योंकि इंटरफ़ेस के तरीकों को आईडीई द्वारा पुनर्प्राप्त किया जाएगा।