मेरी टीम में से एक देवता का मानना है कि किसी विधि के हस्ताक्षर में हर पैरामीटर के लिए एक javadoc टिप्पणी लिखना आवश्यक है। मुझे नहीं लगता कि यह आवश्यक है, और वास्तव में मुझे लगता है कि यह हानिकारक भी हो सकता है।
सबसे पहले, मुझे लगता है कि पैरामीटर नाम वर्णनात्मक और स्व-दस्तावेजीकरण होना चाहिए। यदि यह तुरंत स्पष्ट नहीं है कि आपके पैरामीटर क्या हैं, तो आप शायद इसे गलत कर रहे हैं। हालाँकि, मैं समझता हूँ कि कभी-कभी यह स्पष्ट नहीं होता है कि एक पैरामीटर क्या है, इसलिए उन मामलों में, हाँ, आपको पैरामीटर की व्याख्या करते हुए एक javadoc टिप्पणी लिखनी चाहिए।
लेकिन मुझे लगता है कि हर पैरामीटर के लिए ऐसा करना अनावश्यक है। यदि यह पहले से ही स्पष्ट है कि पैरामीटर क्या है, तो javadoc टिप्पणी बेमानी है; तुम सिर्फ अपने लिए अतिरिक्त काम पैदा कर रहे हो। इसके अलावा, आप किसी ऐसे व्यक्ति के लिए अतिरिक्त कार्य बना रहे हैं जिसे आपके कोड को बनाए रखना है। समय के साथ तरीके बदलते हैं, और टिप्पणियों को बनाए रखना लगभग उतना ही महत्वपूर्ण है जितना कि आपके कोड को बनाए रखना। आपने कितनी बार "एक्स डू वाई फॉर जेड कारण" जैसी टिप्पणी देखी है, केवल यह देखने के लिए कि टिप्पणी आउट-ऑफ-डेट है, और वास्तव में विधि एक्स पैरामीटर को भी नहीं लेती है? यह हर समय होता है, क्योंकि लोग टिप्पणियों को अपडेट करना भूल जाते हैं। मैं तर्क दूंगा कि भ्रामक टिप्पणी किसी भी टिप्पणी की तुलना में अधिक हानिकारक है। और इस तरह ओवर-कमेंटिंग का खतरा है: अनावश्यक दस्तावेज बनाकर, आप '
हालांकि, मैं अपनी टीम के दूसरे डेवलपर का सम्मान करता हूं, और स्वीकार करता हूं कि शायद वह सही है और मैं गलत हूं। यही कारण है कि मैं अपने प्रश्न को आपके साथ ला रहा हूं, साथी डेवलपर्स: क्या वास्तव में EVERY पैरामीटर के लिए एक javadoc टिप्पणी लिखना आवश्यक है? यहां मान लें कि कोड मेरी कंपनी के लिए आंतरिक है, और किसी भी बाहरी पार्टी द्वारा उपभोग नहीं किया जाएगा।