सी कोड, हेडर और स्रोत फ़ाइलों पर टिप्पणी

Question

मैं अपने सी कोड को दस्तावेज करने के लिए "सर्वोत्तम अभ्यास" की तलाश में हूं। किसी भी प्रोजेक्ट की तरह मेरे पास कुछ हेडर फाइलें ".h" हैं और संबंधित स्रोत फ़ाइल ".c"

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

कोड को अच्छी तरह से टिप्पणी करने में आपके सर्वोत्तम अभ्यास क्या हैं?

Answer 1

हेडर कोड के उपयोगकर्ता के लिए है। तो वहां मैं इंटरफेस दस्तावेज करता हूं: इसका उपयोग कैसे करें, पूर्व शर्त और पोस्टकंडिशन, आदि।

.c फ़ाइल रखरखाव के लिए है। वहां, मैं कार्यान्वयन दस्तावेज करता हूं: चीजें आंतरिक रूप से कैसे काम करती हैं, और वे इस तरह से क्यों काम करते हैं।

Answer 2

यदि यह एक निजी परियोजना है तो मैं सुझाव दूंगा कि वहां बहुत सारे coding standards हैं जिन्हें आप अपनाने के लिए कर सकते हैं (लगभग सभी टिप्पणियां कैसे रख सकते हैं)।

यदि नहीं, तो मुझे लगता है कि आपकी कंपनी/चायम/प्रोजेक्ट में पहले से ही कुछ जगह है इसलिए इसका उपयोग करें।

Answer 3

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

cpp फ़ाइलें

Answer 4

स्रोत फ़ाइलें मैं तुम्हें फ़ाइल शीर्ष लेख और समारोह हैडर के लिए एक टिप्पणी टेम्पलेट बनाने का सुझाव के लिए के बारे में थॉमस के साथ सहमत हूँ।

फ़ाइल शीर्षलेख टिप्पणियों के मामले में, आपके पास फ़ाइल, फ़ंक्शन नाम, लेखक, निर्माण की तारीख और इतिहास को संशोधित करने के लिए इतिहास का संक्षिप्त विवरण होना चाहिए।

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