सी ++: कोड प्रलेखन कहां लिखना है: .cpp या .hpp फ़ाइलों में?

Question

कक्षाओं और विधियों के इन-कोड दस्तावेज़ लिखना प्रथागत कहां है?

क्या आप हेडर (.hpp) फ़ाइल में या स्रोत (.cpp) फ़ाइल में संबंधित वर्ग/विधि के ऊपर ऐसे दस्तावेज़-ब्लॉक लिखते हैं?

क्या ऐसी चीजों के लिए व्यापक रूप से सम्मानित सम्मेलन है? क्या अधिकांश सी ++ परियोजनाएं दूसरे की बजाय इसे एक तरह से करती हैं?

या दस्तावेज को दोनों तरफ (यानी .एचपीपी और। सीपीपी फाइलों में) लिखा जाना चाहिए, हो सकता है कि एक छोटे से विवरण के साथ एक तरफ और दूसरी तरफ एक लंबा हो?

सबसे महत्वपूर्ण बात यह है कि क्या कोई व्यावहारिक विचार है जो इसे किसी अन्य तरीके से लिखने के लिए और अधिक सुविधाजनक बनाता है? (उदा स्वत: प्रलेखन पारसर्स और Doxygen ... की तरह जनरेटर का उपयोग)

Answer 1

दोनों:

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

टिप्पणी कुछ भी स्पष्ट नहीं है, और कुछ भी नहीं है कि है (जब तक कि आपके दस्तावेज़ उपकरण के बिना अच्छा प्रलेखन के उत्पादन के लिए भी बेवकूफ है)।

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

Answer 2

आप एक पुस्तकालय बनाने हैं, तो आप आम तौर पर संकलित पुस्तकालय और हेडर फाइल वितरित करते हैं। यह हेडर फ़ाइलों में दस्तावेज़ डालने के लिए सबसे उपयोगी बनाता है।

Answer 3

फिर से, दोनों। सार्वजनिक दस्तावेज़ीकरण के लिए, .x में होना अच्छा है, डॉक्सिजन के साथ निकाले गए स्वरूप के साथ, उदाहरण के लिए, जैसा कि अन्य ने टिप्पणी की है। मुझे चीजों को दस्तावेज करने का पर्ल तरीका बहुत पसंद है। .pl (या .pm) फ़ाइल में स्वयं प्रलेखन शामिल है जिसे एक उपकरण का उपयोग करके निकाला जा सकता है जैसा कि डॉक्सिजन सी ++ कोड के लिए करता है। साथ ही, डॉक्सिजन आपको कई अलग-अलग पेज बनाने की अनुमति देता है, जो आपको उपयोगकर्ता मैनुअल इत्यादि शामिल करने की इजाजत देता है, न केवल स्रोत कोड या एपीआई दस्तावेज करता है। मुझे आम तौर पर साक्षर प्रोग्रामिंग के दर्शन में स्वयं निहित .h/.hpp फ़ाइल का विचार पसंद है।

Answer 4

मुझे व्यक्तिगत रूप से हेडर फ़ाइलों में दस्तावेज़ पसंद है। हालांकि, कुछ ऐसे हैं जो मानते हैं कि प्रलेखन स्रोत फ़ाइलों में डाला जाना चाहिए। इसका कारण यह है कि जब कुछ बदलता है, तो दस्तावेज़ आपको ठीक करने के लिए याद दिलाता है। मैं कुछ हद तक सहमत हूं, क्योंकि जब मैं स्रोत फ़ाइलों में कुछ बदलता हूं तो हेडर में डोक्सिजन टिप्पणियां अपडेट करने के लिए मैं व्यक्तिगत रूप से भूल गया हूं।

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

Answer 5

सबसे महत्वपूर्ण बात, वहाँ किसी भी व्यावहारिक दृष्टिकोण यह अधिक सुविधाजनक यह एक तरह से लिखने के लिए करता है कि के बजाय दूसरी तरह कर रहे हैं?

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

यदि टिप्पणियां .cpp फ़ाइल में हैं, तो यह केवल उस फ़ाइल को पुन: संकलित करेगा। अगर टिप्पणियां .hpp फ़ाइल में हैं, तो यह प्रत्येक .cpp फ़ाइल को उस शीर्षलेख पर निर्भर करता है। .cpp फ़ाइलों में आपकी टिप्पणियां रखने का यह एक अच्छा कारण है।

(जैसे स्वत: प्रलेखन पारसर्स और Doxygen तरह जनरेटर की उपयोग ...)

Doxygen आप अपनी टिप्पणी किसी भी तरह से लिखने के लिए अनुमति देता है।