टिप्पणी लेखन और प्रलेखन में सर्वोत्तम अभ्यास

Question

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

हालाँकि हम अभी भी एक ऐसे युग में रहते हैं जहाँ अक्सर अच्छे डेवलपर्स द्वारा लिखित अप्रचलित या खराब टिप्पणियां होती हैं - मैं अपनी टिप्पणियों की मजबूती और उपयोगिता को बेहतर बनाने में रुचि रखता हूं।

विशेष रूप से मैं यहाँ जावा / क्लोजर / पायथन में रुचि रखता हूं, लेकिन उत्तर भाषा-विशिष्ट होने की आवश्यकता नहीं है।

क्या कोई उभरती हुई तकनीक है जो टिप्पणियों को मान्य करती है और स्वचालित रूप से या तो "टिमटिमाती हुई" टिप्पणियों (उदाहरण के लिए जादुई संख्या, अधूरे वाक्य, आदि ..) या गलत टिप्पणी (उदाहरण के लिए, गलत तरीके से चर या जैसे का पता लगाने वाली) का पता लगाती है।

और अधिक महत्वपूर्ण बात: क्या वहाँ "टिप्पणी-नीतियों" या रणनीतियों को स्वीकार किया जाता है? वहाँ कैसे कोड के बारे में सलाह के बहुत सारे है - लेकिन क्या "कैसे टिप्पणी करने के लिए?"

Answer 1

• नाम / प्रलेखन आपको बताएंगे कि आप क्या कर रहे हैं।

• कार्यान्वयन आपको यह बताना चाहिए कि आप इसे कैसे कर रहे हैं।

• टिप्पणियाँ आपको बताएंगी कि आप इसे वैसे ही क्यों करते हैं जैसे आप करते हैं।

Comments

टिप्पणियों को आपको यह भी बताना चाहिए कि आप इसे दूसरे तरीके से क्यों नहीं कर रहे हैं - अर्थात महत्वपूर्ण डिजाइन विकल्प - क्योंकि भविष्य के रखरखावकर्ताओं को यह जानकारी अन्यथा नहीं होगी।

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

— dallin

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

— शाफ़्ट फ्राक

@ डॉलिन: "यह एक मिथक है कि आप सभी कोड को स्पष्ट रूप से लिख सकते हैं कि कोई भी प्रोग्रामर इसे एक नज़र में समझ सकता है", अंकल बॉब आपके साथ एक शब्द रखना चाहेंगे। - "मुझे इस फ़ंक्शन को विवरणात्मक रूप से नाम देने की आवश्यकता नहीं है क्योंकि कोई भी फ़ंक्शन को देखने के लिए फ़ंक्शन में कोड पढ़ सकता है।" कर रहा है!

— कलार

Answer 2

यह विवादास्पद हो सकता है, लेकिन मेरी सलाह के रूप में संभव के रूप में FEW टिप्पणी लिखने के लिए किया जाएगा। इसके बजाय अच्छे, स्पष्ट वर्ग के नाम, चर नाम और विधि के नाम का उपयोग करें। अपना कोड स्पष्ट तरीके से लिखें जो आप कर सकते हैं; और इसे अपने कोड की सबसे महत्वपूर्ण विशेषता मानते हैं (इसके अलावा यह अपनी आवश्यकताओं को पूरा करता है)। केवल एक टिप्पणी लिखें यदि आपने संभवतः जितना संभव हो उतना स्पष्ट किया है, और आपको अभी भी लगता है कि इसे और स्पष्टीकरण की आवश्यकता है।

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

Comments

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

— रॉबर्ट हार्वे

+1 - मुझे यह भी लगता है कि टिप्पणियों का उपयोग केवल यह बताने के लिए किया जाना चाहिए कि कोड क्यों लिखा गया है। मुझे पता है कि क्या if (a == b) then c();करता है, लेकिन अगर मुझे नहीं पता कि यह ऐसा क्यों करता है - कि जब एक टिप्पणी का इस्तेमाल किया जाना चाहिए :)

— डेको

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

— दाऊद का कहना है कि मोनिका

लिखित कोड को स्पष्ट करने के अलावा, हमें TODO टिप्पणियों का उपयोग करके (कोड-स्तर) विचारों, विचारों आदि को बनाए रखना सुनिश्चित करना चाहिए। उदाहरण के लिए, यदि आप एक फ़ंक्शन / क्लास को वर्तमान डेटा आकार को ठीक से संभालने में सक्षम हैं, लेकिन संभावित रूप से 2 वर्षों के बाद लोड को संभालने में विफल हो जाएगा, तो TODO टिप्पणी का उपयोग करके वहां अपना अवलोकन लिखना सुनिश्चित करें। भविष्य के डेवलपर्स वास्तव में आपके प्रयासों की सराहना करेंगे। कोड लिखते समय कभी भी इन चीज़ों को एक अलग txt / शब्द दस्तावेज़ में नोट करने की कोशिश न करें, कोई भी वास्तव में ऐसे दस्तावेज़ों को संदर्भित नहीं करता है।

— TechCoze

यह भी देखें: "टिप्पणियाँ एक कोड गंध हैं"

— gnat

Answer 3

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

Comments

और स्फिंक्स कवरेज मेट्रिक्स प्रदान करने के लिए प्रलेखन के खिलाफ कोड की तुलना करता है।

— एस.लॉट

Answer 4

प्रलेखन को स्वचालित रूप से उत्पन्न करने के लिए कोड टिप्पणी का उपयोग कैसे करें, यह जानने के लिए सबसे आधिकारिक स्थान में से एक निश्चित रूप से डॉक्सीजन है । हालांकि मुझे ऐसे और उपकरण मिल सकते हैं।

यह टिप्पणी लेखन के मानक को परिभाषित करता है जिसे प्रलेखन उत्पन्न करने के लिए स्वचालित रूप से पालन किया जाना चाहिए। हालाँकि, यह अधिक संरचना देता है लेकिन शब्दार्थ को मान्य नहीं करता है; उदाहरण के लिए यदि आप किसी फ़ंक्शन के उद्देश्य का वर्णन करने के लिए भ्रामक अंग्रेजी का उपयोग करते हैं तो यह जाँच नहीं कर सकता है!

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

कोड को अधिक बनाए रखने के लिए - यह व्यावहारिक रूप से अधिक महत्वपूर्ण है कि एक बाहरी दस्तावेज मौजूद है जो कोड का इलाज करने के तरीके की संरचना बनाने में मदद करता है, और फिर कोड के अंदर टिप्पणियों को देखने के लिए प्रतिबंधित किया जाना चाहिए

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

आमतौर पर एक टिप्पणी में 5% से कम कोड होता है। और व्यवहार में, जबकि कोड-समीक्षाएं स्वयं बहुत कम ध्यान आकर्षित करती हैं (विकास के अन्य पहलुओं पर) व्यावहारिक रूप से कठिन है कि टिप्पणियों की भी समीक्षा की जाती है।

Comments

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

— दाऊद का कहना है कि मोनिका

यह आम तौर पर मेरे द्वारा लिखी जाने वाली एक ही तरह की टिप्पणी है, विशेष रूप से यह जानने के लिए कि इसमें क्या आता है और इससे क्या निकलता है (मैं शिथिल टाइप की भाषाओं के साथ काम करता हूं) दस्तावेज के लिए।

— डैनमैन

Answer 5

क्या कोई उभरती हुई तकनीक है जो टिप्पणियों को मान्य करती है और स्वचालित रूप से या तो "टिमटिमाती हुई" टिप्पणियों (उदाहरण के लिए जादुई संख्या, अधूरे वाक्य, आदि ..) या गलत टिप्पणी (उदाहरण के लिए, गलत तरीके से चर या जैसे का पता लगाने वाली) का पता लगाती है।

एक अच्छी तरह से ज्ञात तकनीक है - इसे "कोड-समीक्षा" कहा जाता है, और एक बहन है जिसका नाम "जोड़ी-प्रोग्रामिंग" है। यहाँ "आटोमैटिकली" कुछ भी उम्मीद न करें।

और अधिक महत्वपूर्ण बात: क्या वहाँ "टिप्पणी-नीतियों" या रणनीतियों को स्वीकार किया जाता है? वहाँ कैसे कोड को --- वहाँ पर सलाह के बारे में बहुत है "लेकिन कैसे टिप्पणी करने के लिए?"

"कोड पूरा" में न केवल कैसे कोड के बारे में सभी शामिल हैं, बल्कि "कैसे टिप्पणी करें" पर अध्याय भी हैं, विशेष रूप से स्व-दस्तावेजीकरण कोड लिखने के तरीके पर।

Comments

कोड पूरा करने के लिए +1। रॉबर्ट मार्टिन द्वारा स्वच्छ संहिता में उपयोगी प्रशंसा लिखने पर भी एक अच्छा अध्याय है। मुझे जावा दुनिया के बारे में निश्चित नहीं है लेकिन .NET दुनिया में हमारे पास Resharper है, जो टिप्पणियों में कोड तत्वों के लिए

— स्वचालित

Answer 6

जावा के एक स्रोत से मुझे जो मज़ा आया है वह है ओरेकल का हाउ टू राइट डॉक कमेंट्स फॉर द जवादोक टूल :

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

और आइटम 44: सभी उजागर एपीआई तत्वों के लिए डॉक्टर टिप्पणी लिखें :

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

से प्रभावी जावा 2 संस्करण ।