जावा में बराबरी की तरह अच्छी तरह से समझा तरीकों के लिए प्रलेखन लेखन

Question

क्या व्यापक रूप से ज्ञात विधियों जैसे समतुल्य, तुलना इत्यादि के लिए टिप्पणियां लिखना एक अच्छा अभ्यास है?

नीचे दिए गए कोड पर विचार करें।

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

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

आपके सुझाव क्या हैं?

Comments

आपकी वर्तमान टिप्पणी गलत है। जेनेरिक ऑब्जेक्ट लेने में आपकी विधि हस्ताक्षर सही है, लेकिन आपकी टिप्पणी 'एक ही प्रकार की वस्तु' कहती है।

— c_maker

मैं बल्कि एक टिप्पणी के बारे में बताता हूँ कि इस वस्तु के लिए समानता का क्या अर्थ है। "समानता" एक फिसलन शब्द है। आम लिस्प में, कई समानता कार्य हैं, और आप उपयोग पर उपयुक्त एक को चुनते हैं।

— डेविड थॉर्नले

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

— विनोथ कुमार CM

@Vinoth: "सार्थक तरीका" वही है जो आपको दस्तावेज़ की आवश्यकता है :)

— c_maker

Answer 1

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

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

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

Comments

मुझे विरासत के बारे में पता है। लेकिन कंपनी हमें स्पष्ट जावा डॉक्स लिखने के लिए "अनिवार्य" करती है।

— विनोथ कुमार CM

@Vinoth यदि वह कंपनी की नीति है, तो ऐसा कुछ भी नहीं है जो आप उन्हें लिखने या पॉलिसी बदलने की मांग करने के अलावा अन्य कर सकते हैं। यदि आप आधुनिक विकास साधनों का उपयोग कर रहे हैं, तो यह नीति पुरानी है। यह नीति क्या चलाती है? JavaDoc टिप्पणियों को वेब पेजों में बदल दिया जाता है और आधुनिक IDE आपको सॉफ़्टवेयर लिखते समय JavaDoc टिप्पणियों को देखने देता है, भले ही वह टिप्पणी कहाँ से आए (स्पष्ट या विरासत में मिली हो)।

— थॉमस ओवेन्स

@ थोमस: अनुमति का विकल्प पूछने के बजाय भीख मांगना है: बस चुपचाप नियमों को मोड़ो और देखो कि क्या कोई शिकायत करता है।

— dsimcha

@dsimcha शायद, लेकिन अगर यह दोहराया जाता है, तो यह नौकरी के लिए बुरा हो सकता है। यह एक-या-दो-बंद चीज नहीं है।

— थॉमस ओवेन्स

Answer 2

मेरी टीम में हम आम तौर पर @inheritDocएनोटेशन का उपयोग करते हैं equals()और hashcode()काश हम ऐसा नहीं करते।

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

यह कम से कम दस्तावेज़ में अच्छा है कि क्या विशेषताएं विधि में भाग लेती हैं और यहां तक ​​कि शायद क्यों।

Comments

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

— निकोलस

Answer 3

याद रखें कि टिप्पणियाँ सही होने पर सभी प्रकार के डेवलपर्स की मदद करती हैं।

समस्या यह है कि वे कभी-कभी अपूर्ण होते हैं और सटीक नहीं होते हैं।

ईमानदार होना 2 वस्तुओं की तुलना में मुश्किल हो सकता है (जैसे 2 चालान वस्तुओं की तुलना करना), आपकी विधि भी समय के साथ विकसित हो सकती है और फिर टिप्पणी करने की आवश्यकता होगी।

"उपयोगी और सार्थक" टिप्पणी में विधि का उद्देश्य, नियम आदि दिखाना एक अच्छी बात है।

Answer 4

यह बहुत ही घटिया प्रैक्टिस है जैसे कोड को खाली टिप्पणी के साथ:

/**
 * This method compares the equality of the current object with the object of same type...
 */

यह उपयोगी कुछ भी नहीं कहता है। इससे भी बदतर, यह शैली और व्याकरण दोनों में खराब है:

1. टिप्पणियाँ कभी भी "इस पद्धति" या "इस वर्ग" या "इस" किसी भी चीज़ से शुरू नहीं होनी चाहिए। टिप्पणी स्रोत फ़ाइल में इसके स्थान से एक विधि या वर्ग से जुड़ी है।

2. "ऑब्जेक्ट" को "ऑब्जेक्ट" पढ़ना चाहिए

3. "समानता की तुलना करता है" केवल तभी समझ में आता है जब एक वस्तु में दूसरे की तुलना में अधिक "समानता" हो सकती है। यह फ़ंक्शन "समानता" की तुलना नहीं करता है; यह वस्तुओं की एक दूसरे के साथ समानता का निर्धारण करने के लिए तुलना करता है।

इसके बजाय, टिप्पणी को इंगित करना चाहिए जब दो वस्तुओं को समान माना जाता है। यहां, मैं पूरी तरह से विधि वर्णन को छोड़ दूंगा, और केवल उदाहरण के लिए रिटर्न वैल्यू का दस्तावेजीकरण करूंगा:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

तुच्छ पाने / निर्धारित तरीकों के लिए उत्पन्न टिप्पणियाँ सबसे खराब हैं।

Answer 5

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

बराबरी के लिए, हम यह नोट करना चाहते हैं कि तुलना केवल प्राथमिक कुंजी पर की जाती है जब डेटाबेस समर्थित निकाय की तुलना की जाती है क्योंकि यह पूरी तरह से प्रलेखन के अनुरूप नहीं है Object.equals()।

Answer 6

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

Answer 7

यह जानते हुए कि वे तरीके सामान्य हैं और अधिकांश डेवलपर्स को पता होगा कि वे तब के लिए क्या हैं, IMO, आपको वहां कोई टिप्पणी करने की आवश्यकता नहीं होगी। टिप्पणियां लंबे समय में विश्वसनीय नहीं हैं क्योंकि संभावनाएं हैं कि कार्यान्वयन के अद्यतन होने पर ये अपडेट नहीं हो सकते हैं और भ्रम पैदा कर सकते हैं। इसलिए अपने कोड को पठनीय बनाना हमेशा बेहतर होता है क्योंकि यह वही है जिस पर आप ज्यादातर भरोसा कर सकते हैं।

इसके अलावा, मैं कहूंगा कि यदि आप जो कोड बना रहे हैं / संपादित कर रहे हैं वह सार्वजनिक API के लिए नहीं है, तो बस सामान्य तरीकों के लिए javadocs छोड़ दें क्योंकि ये सिर्फ अव्यवस्था और शोर जोड़ देंगे।