पूरी परियोजना के वर्कफ़्लो को समझने के लिए स्रोत कोड पर टिप्पणी करने के लिए सबसे अच्छा तरीका?

Question

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

Answer 1

Code complete आपकी समस्या के समाधान को बेहतर तरीके से समझा सकता है जो मैंने कभी भी किया था।

Answer 2

मुझे यह हल करने का सबसे अच्छा तरीका एक इकाई परीक्षण ढांचे का उपयोग करके एक कार्यात्मक परीक्षण लिखना है।

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

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

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

Answer 3

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

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

मैं टिप्पणियों पर विशेष रूप से लाइन टिप्पणियों पर बहुत अधिक प्रयास नहीं करता। दिनांक समाप्त हो जाते हैं, क्योंकि कोई इकाई परीक्षण सत्यापित नहीं करता है कि लाइन टिप्पणियां अभी भी मान्य हैं और यहां तक ​​कि मूल्यवान भी, कोई भी कभी अनावश्यक टिप्पणियों को हटा देता है।

Answer 4

अच्छा सवाल। आप जो पूछ रहे हैं उसका हिस्सा कोड रखरखाव से संबंधित है।

• कुछ डिजाइन प्रलेखन लिखें
• पिछले अनुभव से पोषणीय और स्पष्ट रूप से लिखा कोड

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

मैं स्पष्ट और रखरखाव कोड लिखने के महत्व को पर्याप्त तनाव नहीं दे सकता।जब मैंने रॉबर्ट मार्टिन द्वारा Clean Code पढ़ा तो मेरी आंखें हाल ही में खोली गईं। इस पुस्तक में कम से कम पहले अध्यायों को पढ़ने के लिए आप अपने और अपने साथी डेवलपर्स को देय हैं। वह अकेला ही आपके कोड की पठनीयता और रखरखाव में सुधार करेगा।

विचार यह है कि कोड को लगभग एक कथा की तरह पढ़ना चाहिए, जहां तार्किक क्रम में विधियों का पालन किया जाता है, संक्षेप में नामित होते हैं, और कुछ पैरामीटर लेते हैं। ऐसा करने से कोड टिप्पणियों की आवश्यकता लगभग समाप्त हो जाती है, और कोड संरचना में सुधार होता है।