क्या इंटरफ़ेस में जावाडोक टिप्पणियां जोड़ने और कार्यान्वयन में गैर-जावाडोक टिप्पणियां जोड़ने का सही अभ्यास है?क्या जवाडोक टिप्पणियों को कार्यान्वयन में जोड़ा जाना चाहिए?
अधिकांश आईडीई जब आप ऑटो उत्पन्न करते हैं तो कार्यान्वयन के लिए गैर-जावाडॉक टिप्पणियां उत्पन्न करते हैं। ठोस विधि में वर्णन नहीं होना चाहिए?
उन विधियों के लिए जो केवल कार्यान्वयन (ओवरराइड नहीं) हैं, निश्चित रूप से, क्यों नहीं, खासकर यदि वे सार्वजनिक हैं।
यदि आपके पास ओवरराइडिंग स्थिति है और आप किसी भी पाठ को दोहराने जा रहे हैं, तो निश्चित रूप से नहीं। प्रतिकृति विसंगतियों का कारण बनने का एक निश्चित तरीका है। नतीजतन, उपयोगकर्ताओं को आपकी विधि की अलग-अलग समझ होगी कि वे सुपरटेप या उप प्रकार में विधि की जांच करते हैं या नहीं। @inheritDoc का उपयोग करें या एक दस्तावेज प्रदान न करें - आईडीई अपने जावाडोक दृश्य में उपयोग करने के लिए सबसे कम उपलब्ध पाठ लेगा।
एक तरफ के रूप में, यदि आपका ओवरराइडिंग संस्करण सुपरटेप के दस्तावेज़ीकरण में सामान जोड़ता है, तो आप परेशानी की दुनिया में हो सकते हैं। मैंने अपने पीएचडी के दौरान इस समस्या का अध्ययन किया और पाया कि सामान्य लोगों में ओवरराइडिंग संस्करण में अतिरिक्त जानकारी के बारे में कभी भी पता नहीं होगा अगर वे सुपरटेप के माध्यम से आक्रमण कर रहे हैं।
इस समस्या को संबोधित करने वाले प्रोटोटाइप उपकरण की एक प्रमुख विशेषता में से एक था - जब भी आपने कोई विधि बुलाई, तो आपको संकेत मिलता है कि यदि इसका लक्ष्य या किसी संभावित ओवरराइडिंग लक्ष्यों में महत्वपूर्ण जानकारी होती है (उदाहरण के लिए, एक विरोधाभासी व्यवहार)। उदाहरण के लिए, जब मानचित्र पर डालने का आह्वान किया जाता है, तो आपको याद दिलाया जाता था कि यदि आपका कार्यान्वयन ट्रीमैप है, तो आपके तत्वों को तुलनीय होने की आवश्यकता है।
कार्यान्वयन और इंटरफ़ेस दोनों में जावाडोक होना चाहिए। कुछ औजारों के साथ, आप @inheritDoc कीवर्ड के साथ इंटरफ़ेस के दस्तावेज़ों का उत्तराधिकारी प्राप्त कर सकते हैं।
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
उत्पन्न जेवाडोक के लिए हाँ इससे कोई फर्क नहीं पड़ता। यदि आप केवल इंटरफ़ेस का उपयोग करके ठोस कार्यान्वयन के संदर्भ घोषित करते हैं तो ऐसा नहीं होता है क्योंकि आईडीई द्वारा इंटरफ़ेस के तरीकों को पुनर्प्राप्त किया जाएगा।
@see यह इंटरफ़ेस में विवरण का एक लिंक उत्पन्न करता है। लेकिन मुझे लगता है कि कार्यान्वयन के बारे में कुछ विवरण भी जोड़ना अच्छा है।
आईएमओ इंटरफ़ेस विधियों से लिंक करने के लिए '@ see' का उपयोग करके एक अच्छा अभ्यास है और यह ज्यादातर मामलों में पर्याप्त है । जब आप इंटरफ़ेस विधि से जवाडोक को कंक्रीट कार्यान्वयन में कॉपी करते हैं तो आप केवल जानकारी डुप्लिकेट करते हैं और यह जल्दी से असंगत हो सकता है। हालांकि, कार्यान्वयन के बारे में कोई अतिरिक्त जानकारी javadoc में जोड़ा जाना चाहिए। – Piotr
अतिरिक्त दस्तावेज़ इंटरफ़ेस से दस्तावेज़ को कॉपी करने के बारे में नहीं है, लेकिन यह समझाने के लिए कि आप विधि और उस तरह की सामग्री को कैसे कार्यान्वित करते हैं। एक इंटरफेस दस्तावेज़ के साथ, आप अपने कार्यान्वयन में परिणामों/उद्देश्यों (आवेदन स्थिति या विधि वापसी) के बारे में बताते हैं, यह समझाने के लिए अच्छा हो सकता है कि आप इस उद्देश्यों को कैसे प्राप्त करते हैं। – redben
कुछ हद तक अच्छा अभ्यास
/**
* {@inheritDoc}
*/
कार्यान्वयन के जावाडोक के रूप में डाल करने के लिए (जब तक वहाँ कुछ अतिरिक्त कार्यान्वयन के विवरण के बारे में विस्तार से बताया जा करने के लिए) है।
एक इंटरफ़ेस होने का बिंदु यह है कि विधि को कई तरीकों से कार्यान्वित किया जा सकता है। अगर मैं सिर्फ टिप्पणियों का वारिस करने जा रहा हूं, तो कार्यान्वयन में टिप्पणी करने का क्या मतलब है? –
मैं उपरोक्त टैग का उपयोग करता हूं और फिर टैग के नीचे कोई अतिरिक्त आवश्यक दस्तावेज डालता हूं। –
Sjoerd सही ढंग से कहता है कि दोनों इंटरफेस और कार्यान्वयन में जावाडोक होना चाहिए। इंटरफ़ेस जावाडोक को विधि के अनुबंध को परिभाषित करना चाहिए - विधि को क्या करना चाहिए, इसमें कौन से इनपुट लेते हैं, इसे किस मूल्य पर वापस जाना चाहिए, और त्रुटि के मामलों में इसे क्या करना चाहिए।
कार्यान्वयन दस्तावेज अनुबंध पर एक्सटेंशन या प्रतिबंध, और कार्यान्वयन के विशेष विवरण, विशेष रूप से प्रदर्शन को ध्यान में रखना चाहिए।
आम तौर पर, जब आप किसी विधि को ओवरराइड करते हैं, तो आप बेस क्लास/इंटरफेस में परिभाषित अनुबंध का पालन करते हैं, इसलिए आप मूल जावाडोक को किसी भी तरह से बदलना नहीं चाहते हैं। इसलिए @inheritDoc या @see टैग का उपयोग अन्य उत्तरों में उल्लिखित टैग की आवश्यकता नहीं है और वास्तव में केवल कोड में शोर के रूप में कार्य करता है।
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
तथ्य यह है कि कुछ उपकरण (! मैं, आप कम से देख रहा हूँ ग्रहण) जब एक विधि अधिभावी डिफ़ॉल्ट रूप से इन उत्पन्न केवल एक दुख की बात है: निर्दिष्ट के रूप में here सभी समझदार उपकरण सुपर क्लास या इंटरफ़ेस से विधि जावाडोक वारिस चीजों की स्थिति, लेकिन बेकार शोर के साथ अपने कोड को अव्यवस्थित करने का औचित्य नहीं है।
वहाँ निश्चित रूप से विपरीत मामला हो सकता है, जब आप वास्तव में अधिभावी विधि (आमतौर पर कुछ अतिरिक्त कार्यान्वयन विवरण या अनुबंध थोड़ा सख्त बनाने) के लिए एक टिप्पणी जोड़ना चाहते हैं। लेकिन इस मामले में, आप लगभग इस तरह कुछ नहीं करना चाहते:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/
क्यों? क्योंकि विरासत में टिप्पणी संभवतः बहुत लंबी हो सकती है। ऐसे मामले में, 3 लंबे पैराग्राफ के अंत में अतिरिक्त वाक्य कौन देखेगा ?? इसके बजाय, बस अपनी टिप्पणी का टुकड़ा लिखें और यह सब कुछ है। सभी जावाडोक उपकरण हमेशा को लिंक द्वारा निर्दिष्ट किया गया है जिसे आप बेस क्लास टिप्पणी पढ़ने के लिए क्लिक कर सकते हैं। उन्हें मिश्रण करने में कोई बात नहीं है।
यह एकमात्र सही उत्तर है! – user219882
क्या आप पहले से ही नहीं जानते हैं कि TreeMap का उपयोग करते समय तत्वों की तुलना करने योग्य की आवश्यकता है? एक कार्यान्वयन को विवादित व्यवहार को भी लागू नहीं करना चाहिए। –
मुझे लगता है कि यह सही जवाब होना चाहिए http://stackoverflow.com/a/39981265/419516 – user219882