कोड प्रलेखन: सार्वजनिक बनाम गैर-सार्वजनिक?

Question

मैं उन डेवलपर्स में से एक हूं जिनकी मानसिकता है कि लिखा गया कोड आत्म-व्याख्यात्मक होना चाहिए और एक किताब की तरह पढ़ना चाहिए।

अन्य लोगों के लिए पुस्तकालय कोड विकसित करते समय, उपयोग करने के लिए मैं हेडर फ़ाइलों में अधिक से अधिक दस्तावेज लगाने की कोशिश कर सकता हूं; जो सवाल उठाता है: क्या गैर-लोकतांत्रिक तरीके के दस्तावेज भी समय के लायक हैं? वे उन्हें सीधे उपयोग नहीं करेंगे, वास्तव में, वे नहीं कर सकते। उसी समय यदि मैं कच्चा कोड (यद्यपि, अनिच्छा से) वितरित करता हूं, तो वे गैर-सार्वजनिक तरीके दिखाई देंगे और उन्हें समझाने की आवश्यकता हो सकती है।

बस कुछ मानकों और प्रथाओं की तलाश है जो आप सभी अपनी यात्रा में देखते हैं या उपयोग करते हैं।

Answer 1

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

उस ने कहा, अमूर्त बनाए रखने के लिए उन्हें गैर-हेडर स्रोत कोड (सार्वजनिक रूप से प्रलेखित के बजाय) तक सीमित रखने के लिए एक वैध मामला हो सकता है।

यह सब बल्कि व्यक्तिपरक है, तुम मन हो।

Comments

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

Answer 2

ठीक है, मैं विविधता के लिए तस्वीर पर टिप्पणी / दस्तावेज करने का अपना तरीका जोड़ता हूं। तर्क यह है कि मैं उन कार्यों या सदस्य कार्यों का वर्णन करने से बचता हूं जो केवल हेडर में घोषित किए जाते हैं। एक तरफ मुझे हेडर में बहुत अधिक शोर जोड़ने का डर है। दूसरी ओर साथ में डॉक्यूमेंटेशन मैच को बनाए रखने के लिए आसान है। Doxygen किसी भी तरह से परवाह नहीं करता है और यदि आवश्यक हो तो निजीकरण को फ़िल्टर कर सकता है।

क्लास हेडर में:

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

कक्षा कार्यान्वयन कोड में:

• हेडर की तरह ही स्थानीय घोषणाएँ
• फ़ंक्शन परिभाषाएँ हमेशा (पूर्ण अनुबंध)
• सदस्य फ़ंक्शन परिभाषाएं हमेशा (पूर्ण अनुबंध या वर्चुअल ओवरराइड की जड़ के संदर्भ में)
• स्थिर चर यदि कोई हो (उद्देश्य क्यों)

टेम्पलेट हेडर में:

• ऊपर विलय और
• टेम्पलेट तर्कों के लिए उपयुक्त / अनुपयुक्त प्रकार और
• कितनी अच्छी तरह से उपयुक्तता का पता लगाया जाता है

Answer 3

private:निजी खंड की शुरुआत पर मौजूद सारे दस्तावेज़ उपयोगकर्ताओं की जरूरत है चाहिए।

Answer 4

दस्तावेज़ीकरण किसी भी दिन इसके लायक है, यह मामलों और कहानियों को संक्षिप्त तरीके से समझाने में मदद करता है। कितना कोड कभी स्वयं व्याख्यात्मक है यह व्यापार को आसानी से कहानी कहने की कुछ पंक्तियों के रूप में समझा नहीं सकता है। कोड को निश्चित रूप से उपयोगकर्ता को तर्क के माध्यम से समझने की आवश्यकता होगी कि क्या चल रहा है। :-) मेरे 2 सेंट ...

Comments

ठीक है, लेकिन आप सार्वजनिक एपीआई और आंतरिक कामकाज के लिए प्रलेखन के बीच अंतर को संबोधित नहीं करते हैं।

— लाइटनेस रेस

Answer 5

निश्चित रूप से!

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

प्रलेखन दूसरों के लिए एक अच्छा उपहार के रूप में नहीं होना चाहिए। प्रलेखन, इसके सभी चेहरों में (अच्छी तरह से चुने हुए चर नाम, स्व-दस्तावेजीकरण वर्ग के नाम, सुव्यवस्थित कोड, ठीक से खंडित तरीके, आदि) हर किसी के लिए एक उपहार है जो आपके कोड के संपर्क में आ सकता है, अपने आप में शामिल है।