डॉक्सीजन, बनाए रखने के लिए बहुत भारी?

Question

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

क्या आपके पास मेरे स्रोत कोड को कुशलता से दस्तावेज़ करने के लिए कुछ सुझाव हैं?

क्या कुछ संपादक (मौजूदा संपादक के लिए प्लगइन) निम्नलिखित करने के लिए डॉक्सिजन के लिए कुछ मौजूद हैं?

• स्वचालित रूप से अनसंक्रनाइज़ कोड/टिप्पणी ट्रैक करता है और प्रोग्रामर को इसके बारे में चेतावनी देता है।
• स्वतः ही हर नए आइटम के लिए स्रोत कोड (टेम्पलेट) में Doxygen टिप्पणी प्रारूप (उदाहरण के लिए उस में पैरामीटर नाम के साथ टेम्पलेट) जोड़ने

पुनश्च: मैं एक C/C++ परियोजना पर काम कर रहा हूँ।

Answer 1

क्या यह डॉक्सिजन सिंटैक्स आपको मुश्किल लगता है? या यह तथ्य है कि आपको अब सभी कार्यों पर टिप्पणी करना है।

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

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

1. क्या समारोह
2. मापदंडों
3. वापसी कोड
4. किसी भी प्रमुख चेतावनी/के बारे में सीमाओं करता है समारोह।

यह आपके द्वारा उपयोग किए जाने वाले दस्तावेज़ टूल के बावजूद सच है।

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

• आपको हमेशा @ संक्षिप्त और विस्तृत विवरण की आवश्यकता नहीं है।
• आपको टिप्पणियों में फ़ंक्शन नाम देने की आवश्यकता नहीं है।
• आपको फ़ंक्शन प्रोटोटाइप और कार्यान्वयन पर टिप्पणी करने की आवश्यकता नहीं है।
• आपको प्रत्येक फ़ाइल के शीर्ष पर फ़ाइल नाम की आवश्यकता नहीं है।
• आपको टिप्पणियों में संस्करण इतिहास की आवश्यकता नहीं है। (आप एक संस्करण नियंत्रण उपकरण का उपयोग कर रहे हैं, है ना?)
• आपको "अंतिम संशोधित दिनांक" या इसी तरह की आवश्यकता नहीं है।

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

Answer 2

मुझे लगता है कि आप जो कुछ भी टिप्पणी में डालते हैं, उसे वापस लेते हैं, कक्षा में अच्छी तरह से टिप्पणी करने में 5 मिनट 3 महीने के समय में जब कक्षा को मूल लेखक (वास्तव में कभी-कभी मूल लेखक) के अलावा किसी अन्य व्यक्ति द्वारा बदला जाना चाहिए, पकड़ने के लिए बहुत कम समय ले लो।

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

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

Answer 3

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

Answer 4

यह वास्तव में इस बात पर निर्भर करता है कि आपने अपने दस्तावेज़ में कितनी जानकारी डाली है।

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

सुझाव:

• केवल अपने सार्वजनिक इंटरफेस दस्तावेज़।
• फ़ंक्शन क्या करता है इसके बारे में केवल न्यूनतम दस्तावेज करें।
• एक ऐसे संपादक का उपयोग करने का प्रयास करें जिसमें समर्थन है (अधिकांश करें) या एक प्लगइन है।

जब आप 6 महीने के समय में अपना कोड संपादित करने के लिए आते हैं तो आपको खुशी होगी ...

Answer 5

टिप्पणियों का उपयोग करने के तरीके, या आप कैसे विकसित होते हैं, इस बारे में कुछ गड़बड़ है।

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

यदि आप कार्यों के आंतरिक प्रवाह को दस्तावेज करने के लिए डॉक्सिजन का उपयोग कर रहे हैं, तो आपको शायद इस दृष्टिकोण पर पुनर्विचार करना चाहिए (और फिर भी, इन टिप्पणियों को इतना नहीं बदला जाना चाहिए)। जब आपके पास कोई फ़ंक्शन होता है जो कुछ मान की गणना करता है तो एक टिप्पणी /// Calculating xy using the abc algorithm निश्चित रूप से ऐसा कुछ है जो प्रत्येक दिन नहीं बदला जाना चाहिए।

Answer 6

बिल्कुल सही नहीं है कि आप क्या खोज रहे हैं लेकिन यह Vim plugin आपकी परिभाषाओं के शीर्ष पर डॉक्सीजन स्टब उत्पन्न कर सकता है। यह बहुत अच्छी तरह से काम करता है।

Answer 7

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

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

Answer 8

नीचे बताएं कि आपकी शैली आपकी आवश्यकताओं के अनुरूप है या नहीं। यह सी-एफ़िन है, लेकिन हो सकता है कि आप इसे अपने सिरों के लिए पर्याप्त खींच सकें।

///\file 

/// Brief description goes here 
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
    /// @retval 1 will not do so for parameters. (see below) 
PLL_start( 
    unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the 
          ///  comment will go also. \n 
          /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n 
          /// 2-32767: whatever 
    int param)    ///< 0: crash \n 
          /// 1: boom \n 
          /// 2: bang! 
{ 
    /** 
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS! 
    * - Explain in list form. 
    * - It really helps the maintainer to grok the code faster. 
    * 
    *@attention Explain misuses which aren't caught at runtime. 
    * 
    *@pre Context: 
    * - This function expects only a small stack ... 
    * - The call is either blocking or non-blocking. No access to global data. 
    * 
    *@post The Foobar Interrupt is enabled. Used system resources: 
    * - FOO registers 
    * - BAR interrupts 
    */ 
    /**@post This is another postcondition. */ 
} 

Answer 9

Doxygen के अलावा मुझे लगता है कि आप Code Rocket पर एक नज़र रखना चाहिए।

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

यह स्वचालित रूप से आपको प्रलेखन के रूप में आपकी विधि सामग्री के फ्लोचार्ट और छद्म कोड दृश्यता प्रदान करेगा।

Answer 10

डॉक्सीजन की शक्तियों का उपयोग करें - यह आपको टिप्पणी जोड़ने के बिना कक्षा और विधि विवरण उत्पन्न करेगा (डिफ़ॉल्ट रूप से नहीं - EXTRACT_ALL = YES सेट करें)।

मैं प्रत्येक पैरामीटर को दस्तावेज नहीं करता क्योंकि मुझे लगता है कि उनके नाम उनके लिए ऐसा करना चाहिए (*)।

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

मैं टिप्पणियों को सार्थक होना चाहता हूं - अगर मुझे कोई टिप्पणी दिखाई देती है तो यह खड़ा होगा और मैं ध्यान देउंगा।

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