"स्रोत" और "हेडर" फ़ाइल (मुख्य रूप से C और C ++) के बीच अंतर करने वाली भाषाओं में, क्या हेडर फ़ाइल में दस्तावेज़ों को बनाना बेहतर है:
/**
* time_now - return the current time
*
* Example:
* printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
*/
struct timeval time_now(void);
या स्रोत फ़ाइल में?
(PostgreSQL से प्राप्त)
/*
* Convert a UTF-8 character to a Unicode code point.
* This is a one-character version of pg_utf2wchar_with_len.
*
* No error checks here, c must point to a long-enough string.
*/
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...
ध्यान दें कि कुछ चीजें हेडर में ही परिभाषित की जाती हैं, जैसे कि संरचना, मैक्रोज़ और static inlineफ़ंक्शन। मैं केवल उन चीजों के बारे में बात कर रहा हूं जो हेडर फ़ाइल में घोषित की गई हैं और स्रोत फ़ाइल में परिभाषित की गई हैं।
यहां कुछ तर्क दिए गए हैं, जिनके बारे में मैं सोच सकता हूं। मैं स्रोत फ़ाइल में दस्तावेज़ीकरण की ओर झुक रहा हूं, इसलिए मेरे "प्रो-हेडर" तर्क कुछ कमजोर हो सकते हैं।
समर्थक हैडर:
- प्रलेखन देखने के लिए उपयोगकर्ता को स्रोत कोड की आवश्यकता नहीं है।
- स्रोत प्राप्त करने के लिए असुविधाजनक, या असंभव भी हो सकता है।
- यह इंटरफ़ेस और कार्यान्वयन को अलग रखता है।
समर्थक स्रोत:
- यह हेडर को बहुत छोटा बना देता है, जिससे पाठक को समग्र रूप से मॉड्यूल की एक पक्षी-दृष्टि मिलती है।
- यह अपने कार्यान्वयन के साथ एक फ़ंक्शन के प्रलेखन को जोड़ देता है, यह देखना आसान है कि एक फ़ंक्शन वह करता है जो वह कहता है।
जवाब देते समय, कृपया तर्क से सावधान रहें कि कौन से उपकरण और "आधुनिक आईडीई" क्या कर सकते हैं। उदाहरण:
- प्रो-हेडर: कोड फोल्डिंग कमेंट हेडर्स को कमेंट छिपाकर अधिक नेविगेट करने में मदद कर सकता है।
- Pro-source: cscope की
Find this global definitionसुविधा आपको हेडर फ़ाइल (जहां घोषणा है) के बजाय स्रोत फ़ाइल (जहाँ परिभाषा है) पर ले जाती है।
मैं यह नहीं कह रहा हूं कि इस तरह के तर्क न दें, लेकिन ध्यान रखें कि हर कोई आपके द्वारा उपयोग किए जाने वाले टूल के साथ उतना सहज नहीं है।