जावाडोक @ लेखक टैग अच्छी प्रथाओं

Question

मैं जावाडॉक्स बनाते समय सर्वोत्तम प्रथाओं के बारे में सोच रहा हूं। मेरे पास कई फाइलों के साथ एक परियोजना है। कोड कई डेवलपर्स द्वारा बनाया गया है। प्रत्येक फ़ाइल में एनोटेशन @author है, इसलिए यह स्पष्ट है कि किसने एक विशेष कक्षा बनाई है।

लेकिन जब कोई अन्य डेवलपर फ़ाइल में नया कोड जोड़ता है, इसे संशोधित करता है, आदि, उसे बाकी टीम को कैसे सूचित करना चाहिए कि उसने कुछ नया फ़ंक्शन बनाया है या मौजूदा कोड को संशोधित किया है? दूसरे शब्दों में, हमें "जवाडॉक्स को वास्तविकता के साथ संगत कैसे रखना चाहिए"? ;)

• अपना नाम मौजूदा @author टैग पर जोड़ें? फिर, यह पहचानना आसान है कि किसी भी संदेह के मामले में किससे पूछना है।
• प्रत्येक नई विधि, आंतरिक कक्षा इत्यादि में @author टैग जोड़ें?

बेशक

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

इन @author टैग का उपयोग करने का सबसे अच्छा तरीका क्या है?

Answer 1

मैं कहूंगा कि अधिकांश प्रयोजनों के लिए @author अवांछित शोर है। आपके एपीआई के उपयोगकर्ता को नहीं करना चाहिए - और शायद नहीं - देखभाल, या जानना चाहते हैं, किसने लिखा था।

और, जैसा कि आपने पहले ही कहा है, एसवीएन पहले ही इस जानकारी को कोड के मुकाबले कहीं अधिक आधिकारिक तरीके से रखता है। तो अगर मैं टीम में से एक था, तो मैं हमेशा एसवीएन के लॉग को पसंद करता हूं और @author को अनदेखा करता हूं। मैं शर्त लगाता हूं कि कोड वास्तविकता के साथ सिंक हो जाएगा, जो भी आपने अपनाया है। अपने आप को दोहराएं सिद्धांत के बाद, इस जानकारी को दो स्थानों पर क्यों रखें?

हालांकि, कुछ नौकरशाही या नीति कारण हैं कि इस जानकारी को कोड में शामिल किया जाना चाहिए, क्या आपने चेक इन कोड में कोड में @author टैग को स्वचालित रूप से अपडेट किया है? आप शायद इसे एक एसवीएन हुक के साथ प्राप्त कर सकते हैं। उदाहरण के लिए आप उन सभी डेवलपर्स को सूचीबद्ध कर सकते हैं जिन्होंने किसी दिए गए फ़ाइल को क्रम में बदल दिया है; या इसे सबसे ज्यादा किसने बदल दिया; जो कुछ भी। या, अगर @author को आपके द्वारा बाहर की दुनिया में रिलीज़ (स्रोत) कोड में अनिवार्य है, तो आप रिलीज बिल्ड के हिस्से के रूप में @author स्वचालित रूप से जोड़ने पर विचार कर सकते हैं (मुझे संदेह है कि आप इस जानकारी को किसी भी तरह से एसवीएन से प्राप्त कर सकते हैं)।

एक वर्ग वर्ग @author टैग (या अन्य टिप्पणी) से अधिक जोड़ने के लिए, मैं कहूंगा कि आप बहुत सारे शोर को जमा करेंगे। (फिर, आपके पास एसवीएन है।)

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

Answer 2

आपके पास एक से अधिक @author टैग हो सकते हैं। यदि आप कक्षा में कुछ बड़े बदलाव करते हैं, तो बस इसमें अपने नए नाम के साथ एक नया @author टैग जोड़ें। आपके द्वारा किए गए परिवर्तनों को चिह्नित करने या परिवर्तनों के आस-पास अपना नाम डालने की कोई आवश्यकता नहीं है, क्योंकि संशोधन इतिहास स्पष्ट रूप से प्रदर्शित करने में सक्षम होना चाहिए।

Answer 3

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

http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

मेरी सबसे अच्छी समझ के लिए यह जब स्रोतों कागज पर मुद्रित कर रहे थे से काम करने का एक कार्गो पंथ तरीका है। आधुनिक संस्करण नियंत्रण प्रणाली के साथ इस जानकारी और इतिहास को इतिहास में भी पाया जा सकता है।

Answer 4

बहुत से डेवलपर्स के साथ वास्तव में बड़ी और लंबी चल रही परियोजनाओं में, यह जानना उपयोगी है कि हो कोड के लिए हो जिम्मेदार है, जो आपको अतिरिक्त जानकारी और ऐसे प्रदान कर सकता है। उस स्थिति में @Author टैग का उपयोग कर फ़ाइल में ऐसी जानकारी रखने के लिए आसान होगा। इस बात को चिह्नित नहीं किया कि किसने फ़ाइल बनाई है या किसने कुछ प्रमुख योगदान दिया है, लेकिन उस कोड के लिए संपर्क व्यक्ति कौन है। वे बहुत अलग लोग हो सकते हैं क्योंकि मूल लेखक पहले से ही अलग परियोजना पर हो सकता है या कंपनी को साल पहले छोड़ दिया जा सकता है।

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

समाधान, जो काम कर सकता है, हर फ़ाइल पर @Author रखना नहीं है, बल्कि केवल प्रति मॉड्यूल (उच्च स्तरीय पैकेज) है। जावाडोक में एक सुविधा है, जहां आप न केवल फाइलें बल्कि पूरे पैकेज (See this question for more detail) दस्तावेज कर सकते हैं।

हालांकि यह एक विशेष मामला है और जब तक आपकी परियोजना बड़ी या पुरानी नहीं है, तो मैं लेखक की जानकारी को कम करने का अनुमान लगाता हूं।