सरल गेट्टर / सेटर टिप्पणियां

Question

गेटर्स और सेटर्स पर टिप्पणी करने के लिए आप किस सम्मेलन का उपयोग करते हैं? यह कुछ ऐसा है जो मैंने कुछ समय के लिए सोचा है, उदाहरण के लिए:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

मुझे हमेशा लगता है कि मैं 1a / b और 2a / b के लिए सटीक एक ही बात लिख रहा हूं, 1a जैसा कुछ) कर्मचारी का वेतन सेट करता है, 1b) कर्मचारी का वेतन। यह सिर्फ इतना बेमानी लगता है। अब मैं कुछ और जटिल देख सकता हूँ जो आप संदर्भ देने के लिए (ए) भागों में अधिक लिख सकते हैं, लेकिन अधिकांश गेटर्स / सेटर के लिए वहाँ शब्दांकन लगभग समान है।

मुझे बस उत्सुकता है अगर, सरल गेटर्स के लिए / केवल (ए) भाग या (बी) भाग में भरने के लिए अपना ओके सेट करता है।

तुम क्या सोचते हो?

Comments

एक तरफ के रूप में, कृपया कुछ भी मौद्रिक (जैसे यहां वेतन) के लिए फ्लोट का उपयोग न करें। उदाहरण के लिए देखें stackoverflow.com/questions/965831/…

— जोनिक

इसके बजाए बिगडेसीमल का उपयोग करें।

— जोसेप

Answer 1

मैं आमतौर पर बसने के लिए परम भाग को भरता हूं, और गेटर्स के लिए @ ग्रेट भाग:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

इस तरह से javadoc जाँच उपकरण (जैसे कि ग्रहण की चेतावनियाँ) साफ हो जाएँगी, और कोई दोहराव नहीं है।

Comments

क्या आप टाइपो को ठीक कर सकते हैं? "setters के लिए @return हिस्सा"

— Jonik

वेतन में एक टाइपो भी है () टिप्पणी। यह JavaDoc टिप्पणी नहीं है।

— फोस्टा

मैं मानता हूं कि यह टिप्पणी करने वाले अभिगमकर्ताओं के लिए सबसे अच्छा तरीका है।

— फोस्टा

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

— लाइल

@ लाइल यह सच हो सकता है, लेकिन मुझे ऐसा लगता है कि लगभग हमेशा कुछ उपयोगी होता है जो एक प्रोग्रामर कह सकता है जो एक गेटटर / सेटर का वर्णन करता है, जो कि केवल विधि हस्ताक्षर से बेहतर है। हां, ऐसे मामले हैं जहां एक प्रोग्रामर आलसी है और टिप्पणी में केवल विधि हस्ताक्षर दोहराता है, लेकिन मुझे लगता है कि आम तौर पर बोलना, यह मजबूर करने के लिए एक सहायक व्यवहार है।

— मैट वुकस

Answer 2

बिल्कुल व्यर्थ - आप अपने कोड को अव्यवस्थित करने वाले इस प्रकार के बिना बेहतर हैं:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

बहुत उपयोगी है, अगर वारंट किया गया हो:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

विशेष रूप से इस बात का स्पष्टीकरण कि संपत्ति का वास्तव में क्या मतलब है डोमेन मॉडल में महत्वपूर्ण हो सकता है। जब भी मुझे अस्पष्ट नामों वाली संपत्तियों से भरी बीन दिखाई देती है, जो केवल निवेश बैंकर, बायोकेमिस्ट या क्वांटम भौतिक विज्ञानी ही समझते हैं, और टिप्पणियां बताती हैं कि setGobbledygook () विधि "gobbledygook सेट करती है।", मैं किसी का गला घोंटना चाहता हूं।

Comments

मेरी भावनाएं वास्तव में, सबसे खराब डोमेन विशिष्ट मॉडल हैं जहां केवल एक डोमेन विशेषज्ञ जानता है कि संपत्ति का मतलब क्या है।

— ThaDon

यहां तक ​​कि अगर यह उपयोगी है तो आप getFoo () के लिए क्या करेंगे। क्या आप getFoo () के लिए भी यही टिप्पणी कॉपी करेंगे?

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

@cmv: जाहिर है "परम" भाग की नकल नहीं की जाएगी। मुझे यह पता नहीं है कि क्या दोनों एक्सेसरों से जुड़ी सूचनाओं का मूल्य सीधे सूचनाओं को डुप्लिकेट करने के लिए उचित है। शायद हाँ। इससे भी बेहतर यह होगा कि आप दोनों को एक टिप्पणी दें; मेरा मानना ​​है कि यह प्रोजेक्ट लोम्बोक में उपलब्ध है।

— माइकल बोर्गवर्ड

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

— फ्रीटास

+1 "अस्पष्ट नामों के लिए जो केवल निवेश बैंकरों, जैव रसायनविदों या क्वांटम भौतिकविदों को समझते हैं"

— जैक्सन

Answer 3

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

मुझे पता है कि एक गैर-उत्तर की तरह लगता है, लेकिन मैं अपने समय का उपयोग उन चीजों पर टिप्पणी करने के लिए करने की कोशिश करता हूं, जिन्हें स्पष्टीकरण की आवश्यकता है।

Comments

इन पंक्तियों के साथ एक और मान्य उत्तर हो सकता है "

— गेटर्स और सेटर के

@Trejkaz: सच नहीं है, क्योंकि एक्सेसरी मेथड केवल-या केवल-लिखने के गुणों के लिए, और बहुरूपता के लिए अनुमति देते हैं (और इसलिए रैपिंग, प्रॉक्सिमिंग, और इसी तरह)।

— लॉरेंट पीरिन

वे उन चीजों के लिए अनुमति दे सकते हैं, लेकिन अक्सर एक बिल्डर पैटर्न

— बसने

मुझे निश्चित रूप से बिल्डर पैटर्न पसंद है और इसका उपयोग करते हैं, लेकिन POJOs (उदाहरण के लिए हाइबरनेट) में इतना समर्थन है कि गेटर्स और बसने वालों के पास अभी भी अपना प्रमुख स्थान है, बेहतर या बदतर के लिए। यह जावा, IMHO के बारे में अजीब बात है, और एक दशक से अधिक समय तक दोहराए जाने वाले JavaDocs लिखने के बाद, मैं @ sleske की सलाह के लिए सदस्यता लेने के लिए तैयार हूं।

— माइकल शेपर

Answer 4

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

संपादित करें: इसके अलावा, यदि आप पाते हैं कि आपके गेटटर / सेटर में बहुत सारे साइड इफेक्ट्स शामिल हैं, तो आप एक अलग तरीके का नाम रखने के लिए गेट्टर / सेटर को बदलना चाह सकते हैं (जैसे: स्टैक के लिए पुश और पॉप) [के लिए धन्यवाद नीचे टिप्पणी]

Comments

यकीनन, आपको ऐसे गेटर्स का नाम बदलना चाहिए जिनके साइड इफेक्ट अधिक स्पष्ट हों, क्योंकि सभी डेवलपर्स टिप्पणियों को नहीं पढ़ेंगे।

— akf

यह ठीक है - लेकिन इसके लिए आपके एपीआई के उपयोगकर्ताओं को यह जानना आवश्यक है कि, इसका कोई दुष्प्रभाव हुआ है या नहीं, वे प्रलेखित होंगे !

— बैल_बुल

akf, मैं बिल्कुल सोच रहा था कि पोस्ट करने के बाद :) मुझे लगता है कि मैं इसे अपनी प्रतिक्रिया से जोड़ दूंगा।

— गोपुरखान

लेकिन अगर आप "बेवकूफ" गेटर्स और सेटर्स को दस्तावेज नहीं करते हैं (यह वही है जो मैं पसंद करता हूं, तो भी!) - आपको लापता जावाडॉक पर ग्रहण की चेतावनी से कैसे छुटकारा मिलता है? मैं उस तरह की चेतावनियों के साथ अपने कार्यक्षेत्र को अव्यवस्थित नहीं करना चाहता, लेकिन मैं यह भी नहीं चाहता कि यह चेतावनी अन्य सभी तरीकों से अक्षम हो ...

— Zordid

Answer 5

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

आपके मामले में:

public void setSalary(float s)
public float getSalary()

यह स्पष्ट नहीं है कि वेतन किस रूप में व्यक्त किया गया है। यह सेंट, डॉलर, पाउंड, आरएमबी है।

जब सेटरिंग / गेटर्स का दस्तावेजीकरण होता है, तो मुझे एन्कोडिंग से अलग करना पसंद है। उदाहरण:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

पहली पंक्ति कहती है कि यह ऊँचाई लौटाती है। रिटर्न पैरामीटर दस्तावेज़ जो ऊंचाई मीटर में है।

Comments

जब मैं आपसे सहमत हूं, तो मुझे लगता है कि किसी को यह सुनिश्चित करना होगा कि फ़ंक्शन टिप्पणियां खराब चुने हुए, गैर-स्पष्ट फ़ंक्शन नाम के लिए नहीं बना रही हैं।

— करलिप्लोपिन

मैं JavaDocs का एक बड़ा समर्थक हूं, लेकिन स्व-दस्तावेजीकरण कोड का भी बड़ा समर्थक हूं। तो कम से कम सेटर के लिए, मैं कुछ public void setSalary(float aud)(या अधिक वास्तविक रूप से public void setSalary(BigDecimal aud)) करूँगा । बेहतर अभी तक, संपत्ति को प्रकार का होना चाहिए abstract class CurrencyAmount, जिसके बदले गुण java.util.Currency currencyऔर हैं java.math.BigDecimal amount। अधिकांश डेवलपर्स जिनके साथ मैंने काम किया है, वे JavaDoc के साथ बहुत आलसी हैं, लेकिन एपीआई को इस तरह लागू करना इस समस्या को कम करता है।

— माइकल शेपर

यदि इकाई मीटर / सेकंड जैसी SI इकाई है, तो दस्तावेज़ की आवश्यकता कम होती है, यदि यह Si इकाई नहीं है, तो इसे गैर मानक इकाई में शामिल करने के लिए दस्तावेज या बेहतर नाम दिया जाना चाहिए, जैसे heightFeet

— AlexWien

Answer 6

वे केवल एक संदर्भ टैग शामिल नहीं करते हैं ताकि आपको फ़ील्ड मान और गेटर्स और सेटर्स से संदर्भ बताने दें।

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

ताकि दस्तावेज़ गेटर और सेटर के साथ-साथ फ़ील्ड पर भी लागू हो (यदि निजी javadocs चालू है)।

Comments

मैं सहमत हूँ। और फिर मुझे एहसास हुआ, किसी भी तरह यह सभी बॉयलरप्लेट क्यों लिखते हैं? प्रोजेक्ट लोम्बोक के बारे में मेरा जवाब देखें।

— माइकल शेपर

Answer 7

प्रोजेक्ट लोम्बोक का उपयोग करके इस तरह के बॉयलरप्लेट से बचा जा सकता है । फ़ील्ड चर का केवल दस्तावेज़ करें, भले ही यह हो private, और लोम्बोक एनोटेशन को ठीक से प्रलेखित गेटर्स और सेटर उत्पन्न करते हैं।

मेरे लिए, यह लाभ अकेले लागत के लायक है ।

Answer 8

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

दस्तावेज़ीकरण के बिना, किसी भी कॉलर को यह पता नहीं होगा कि यदि विधि का कोई दुष्प्रभाव होता है, तो स्पष्ट सम्मेलन के बारे में अपनी उंगलियों को पार करने के अलावा।

मुझे यकीन है कि मैं केवल एक ही ऐसा व्यक्ति नहीं हूं, जिसे इस बात का पता लगाने का दुर्भाग्य था कि एक विधि जिसे setXपूरी तरह से एक संपत्ति सेट करने की तुलना में बहुत अधिक कहा जाता है।

Comments

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

— mqp

एक दम बढ़िया! अब क्या यह कंपनी क्रूडटेक है, जिसके एपीआई के खिलाफ मैं कोडिंग कर रहा हूं, आपके सम्मेलन का पालन कर रहा हूं, या क्या यह इस धागे पर किसी और का अनुसरण करता है? Hmmmm

— oxbow_lakes

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

— जोओ मार्कस

आप दस्तावेज़ को यह बताने के लिए कहते हैं कि "यह वही है जो आप उम्मीद करते हैं।" जो एक कप कॉफी पर "सावधानी: गर्म" लिखने जैसा है। एक आदर्श दुनिया में, ऐसी बातों को कभी कहने की आवश्यकता नहीं होगी।

— केविन पैंको

हां - एपीआई का उपयोग करने के तरीके, जहां तरीकों setXको उम्मीद की तुलना में दुष्प्रभाव कहा जाता है, मैं वास्तव में विश्वास के साथ कह सकता हूं कि यह एक आदर्श दुनिया नहीं है।

— oxbow_lakes

Answer 9

अगर गटर / सेटर में विशेष ऑपरेशन नहीं होता है तो मैं आमतौर पर लिखता हूं:

Javadoc के साथ (निजी विकल्प के साथ):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

और / या

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Doxygen के साथ (निजी अर्क विकल्प के साथ):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Comments

इस दृष्टिकोण के साथ समस्या यह है कि Javadoc डिफ़ॉल्ट रूप से निजी प्रलेखन उत्पन्न नहीं करता है! उस स्थिति में संदर्भ टैग {@see #salary}उत्पन्न प्रलेखन में अमान्य है।

— जारेक प्रोजगोडकी

Answer 10

एक्सेसर्स पर टिप्पणी करना, खासकर यदि वे कहीं भी कोई ऑपरेशन नहीं करते हैं, अनावश्यक और उंगलियों की बर्बादी है।

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

यदि दूसरी ओर, आपका person.getFirstName()व्यक्ति किसी व्यक्ति का पहला नाम नहीं लौटाता है ... तो ठीक है, हम वहां नहीं जाएंगे?

Comments

क्या होगा अगर getFirstName () शून्य मिलता है? यह कहां से प्रलेखित किया जाएगा?

— स्टीव कू

सुरक्षा के बारे में कैसे ।getFinalMaturity ()? सभी संपत्ति के नाम का तुरंत समझने योग्य अर्थ नहीं है। क्या आप इसका मतलब नहीं जानने के लिए निकाल दिया जाना चाहेंगे?

— माइकल बोरगवर्ड

यदि स्विज़लिंग द्वारा विधि को लागू किया जाता है तो क्या होगा? आपको यह कैसे पता होना चाहिए कि जब तक यह स्पष्ट रूप से प्रलेखित नहीं किया गया है? आपको कैसे पता चलेगा कि यह एक मानक सेटर है जब तक कि डॉक्टर यह नहीं कहता है?

— oxbow_lakes जुआन

मेरी राय में / गेट सेट और गेटर्स के लिए आरक्षित होना चाहिए। डेटाबेस लुकअप को "लुकअप पर्सन" या जैसे नाम दिया जाना चाहिए।

— थोर्बोजर्न रेव एंडरसन

Answer 11

यदि फ़ील्ड का नाम सामग्री का पर्याप्त विवरण नहीं है, तो कुछ भी न डालें।

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

संपादित करें: उपरोक्त केवल पाने और बसने के लिए संदर्भित करता है। मेरा मानना ​​है कि कुछ भी गैर तुच्छ ठीक से javadoc'ed होना चाहिए।

Comments

टिप्पणी और दस्तावेजीकरण में अंतर है।

— टॉम हॉल्टिन - 20

सच सच। वास्तव में इसलिए मैं गेटर्स और सेटर की टिप्पणी नहीं करता। उन्हें स्वयं व्याख्यात्मक होना चाहिए, और एक टिप्पणी जोड़ना यह दर्शाता है कि कोड स्वयं व्याख्यात्मक नहीं है।

— थोरबजोरन राव एंडरसन

Answer 12

(बी) भाग को भरना ठीक है, खासकर यदि आप क्षेत्र की घोषणा पर टिप्पणी करते हैं जो यह दर्शाता है कि क्षेत्र क्या है।

Comments

कोई अच्छा - लोगों को क्षेत्र टिप्पणियों पढ़ा नहीं है। Javadoc डिफ़ॉल्ट रूप से निजी दस्तावेज़ भी उत्पन्न नहीं करता है, और जब आप किसी विधि कॉल पर त्वरित सहायता का उपयोग करते हैं, तो IDE आपको फ़ील्ड दस्तावेज़ नहीं दिखाता है।

— ट्रेकजाज़

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

— akf

Answer 13

यदि javadoc में कुछ भी नहीं जोड़ा जाता है, तो मैं javadoc को हटाता हूं और स्वतः-जनरेट की गई टिप्पणियों का उपयोग करता हूं।

Answer 14

मैं हमेशा दोनों में भरता हूं। अतिरिक्त समय बिताया टाइपिंग नगण्य है, और अधिक जानकारी सामान्य रूप से कम से बेहतर है।

Comments

वे केवल आत्म-व्याख्यात्मक हैं यदि आप कहते हैं "यह एक संपत्ति सेटर है"। अन्यथा एपीआई के एक ग्राहक को इस बात का कोई अंदाजा नहीं है कि वास्तव में तरीकों के अंदर क्या हो रहा है

— oxbow_lakes

आत्म-व्याख्यात्मक के बारे में कुछ भी किसने कहा?

— पॉल सोनियर