दस्तावेज कोड कैसे?
आपके पास पहले से ही एक संकेत है: देखो कि जावा एपीआई कैसे प्रलेखित है।
आम तौर पर, नियमों का कोई अनूठा सेट नहीं है जो हर परियोजना पर लागू होता है। जब मैं व्यावसायिक-महत्वपूर्ण बड़े पैमाने पर परियोजनाओं पर काम करता हूं, तो दस्तावेज़ीकरण का मेरे पास एक छोटे से खुला स्रोत पुस्तकालय के लिए लिखने के लिए कुछ भी नहीं होता है, जो बदले में, मेरे मध्यम-स्तरीय व्यक्तिगत परियोजना के प्रलेखन से कोई लेना-देना नहीं है। ।
क्यों कई खुले स्रोत परियोजनाओं को अच्छी तरह से प्रलेखित नहीं किया जाता है?
क्योंकि ज्यादातर ओपन सोर्स प्रोजेक्ट्स उन लोगों द्वारा किए जाते हैं जो उन प्रोजेक्ट्स में योगदान करते हैं क्योंकि यह मजेदार है। अधिकांश प्रोग्रामर और डेवलपर्स यह मानते हैं कि लेखन दस्तावेज मुफ्त में किए जाने के लिए पर्याप्त मजेदार नहीं है ।
क्यों कई बंद स्रोत परियोजनाओं को अच्छी तरह से प्रलेखित नहीं किया जाता है?
क्योंकि इसमें एक बड़ी रकम खर्च होती है (1) अच्छा दस्तावेज लिखना और (2) इसे बनाए रखना।
तत्काल लागत (दस्तावेज लिखने की लागत) हितधारकों को स्पष्ट रूप से दिखाई देती है: यदि आपकी टीम परियोजना के दस्तावेज के अगले दो महीने खर्च करने के लिए कहती है, तो यह भुगतान करने के लिए दो महीने का अतिरिक्त वेतन है।
दीर्घकालिक लागत (प्रलेखन को बनाए रखने की लागत) प्रबंधकों के लिए भी बहुत आसान हो जाती है, और अक्सर यह पहला लक्ष्य होता है जब उन्हें लागत कम करनी चाहिए या देरी को कम करना चाहिए। यह पुरानी प्रलेखन की एक अतिरिक्त समस्या का कारण बनता है जो जल्दी बेकार हो जाता है, और अद्यतन करने के लिए बहुत महंगा है।
लंबी अवधि की बचत (कुछ दिन बर्बाद करने से बचती है, विरासत कोड की खोज करने के लिए बस एक बुनियादी बात को समझना चाहिए जो वर्षों पहले प्रलेखित किया जाना चाहिए था), दूसरी ओर, मापना मुश्किल है, जो कुछ प्रबंधकों की भावना की पुष्टि करता है उस लेखन और प्रलेखन को बनाए रखना समय की बर्बादी है।
मैं अक्सर यह देखता हूं कि:
शुरुआत में, टीम एक बहुत दस्तावेज करने के लिए तैयार है।
समय के साथ, समय सीमा और ब्याज की कमी के दबाव ने प्रलेखन को बनाए रखने के लिए इसे और अधिक कठिन बना दिया।
कुछ महीने बाद, एक नया व्यक्ति जो परियोजना में शामिल होता है, व्यावहारिक रूप से प्रलेखन का उपयोग नहीं कर सकता है, क्योंकि यह वास्तविक प्रणाली के अनुरूप नहीं है।
यह देखते हुए कि, प्रबंधन प्रलेखन बनाए रखने के लिए डेवलपर्स को दोषी ठहराता है; डेवलपर्स इसे अपडेट करने में कुछ सप्ताह बिताने को कहते हैं।
यदि प्रबंधन उस के लिए कुछ सप्ताह देता है, तो चक्र दोहराता है।
यदि प्रबंधन पिछले अनुभव के आधार पर मना कर देता है, तो यह केवल खराब अनुभव को बढ़ाता है, क्योंकि उत्पाद में प्रलेखन का अभाव है, लेकिन कुछ महीने इसे लिखने और बनाए रखने में बिताए गए थे।
परीक्षण की तरह ही प्रलेखन एक सतत प्रक्रिया होनी चाहिए। एक सप्ताह बिताओ बस कुछ हजारों LOC कोडिंग, और परीक्षण और प्रलेखन के लिए वापस बहुत, बहुत दर्दनाक है।
प्रलेखन लिखने के लिए टीम को कैसे प्रोत्साहित करें?
इसी तरह लोगों को स्वच्छ कोड लिखने के लिए प्रोत्साहित करने के लिए, नियमित रूप से रीफैक्टरिंग करने के लिए, डिज़ाइन पैटर्न का उपयोग करने के लिए या पर्याप्त इकाई परीक्षणों को जोड़ने के लिए।
मिसाल पेश करके। यदि आप अच्छे दस्तावेज लिखते हैं, तो आपके जोड़े भी ऐसा करना शुरू कर सकते हैं।
प्रलेखन का निरीक्षण करने पर लक्षित औपचारिक कोड समीक्षा सहित व्यवस्थित कोड समीक्षाएं करें।
यदि टीम के कुछ सदस्य विशेष रूप से अच्छे प्रलेखन (या सभी पर प्रलेखन) के लिए विरोधी हैं, तो उनके साथ इस विषय पर चर्चा करें कि यह समझने के लिए कि क्या बाधाएं हैं जो उन्हें बेहतर दस्तावेज लिखने से रोकती हैं। यदि वे समय की कमी को दोष देते हैं, तो आप समस्याओं का स्रोत देखते हैं।
कुछ हफ़्ते या महीनों के लिए औसत दर्जे की उपस्थिति या प्रलेखन की कमी करें, लेकिन उस पर ध्यान केंद्रित न करें। उदाहरण के लिए, आप प्रति LOC टिप्पणियों की संख्या को माप सकते हैं, लेकिन इसे स्थायी उपाय न बनाएं, अन्यथा, डेवलपर्स कम स्कोर से छुटकारा पाने के लिए लंबे लेकिन अर्थहीन टिप्पणी लिखना शुरू कर देंगे।
सरगम का उपयोग करें। यह पिछले बिंदु के साथ आता है।
सकारात्मक / नकारात्मक सुदृढीकरण का उपयोग करें ।
( SJuan76 द्वारा टिप्पणी देखें ) त्रुटियों के रूप में टिप्पणियों की कमी का इलाज करें। उदाहरण के लिए, Visual Studio में, आप XML प्रलेखन उत्पन्न करने के लिए एक विकल्प की जाँच कर सकते हैं। यदि आप यह भी जाँचते हैं कि सभी चेतावनियाँ त्रुटियों के रूप में मानी जाती हैं, तो किसी वर्ग या विधि के शीर्ष पर एक टिप्पणी का अभाव संकलन को रोक देगा।
पिछले तीन बिंदुओं के लिए, इस एक का उपयोग सावधानी के साथ किया जाना चाहिए। मैंने शुरुआती प्रोग्रामर की विशेष रूप से कठिन टीम के साथ थोड़ी देर के लिए इसका इस्तेमाल किया, और यह स्टाइलकॉप-अनुरूप जैसे कि समाप्त हो गया:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
जो, हम्म ..., विशेष रूप से उपयोगी नहीं थे।
याद रखें: जब प्रोग्रामर आपके साथ पंगा लेना चाहते हैं तो कुछ भी स्वचालित आपको बुरी टिप्पणियों को इंगित करने में मदद नहीं कर सकता है । केवल कोड समीक्षा और अन्य मानवीय कार्यों में मदद मिलेगी।
क्या कोई अच्छा उदाहरण है जब न्यूनतम या कोई प्रलेखन की आवश्यकता होती है?
वास्तुकला और डिजाइन की व्याख्या करने वाले प्रलेखन की आवश्यकता नहीं है:
एक प्रोटोटाइप के लिए,
किसी कार्य को पूरा करने के लिए कुछ घंटों में लिखे गए एक व्यक्तिगत प्रोजेक्ट के लिए, यह सुनिश्चित करते हुए कि इस परियोजना को अब और बनाए नहीं रखा जाएगा,
किसी भी परियोजना के लिए जहां यह स्पष्ट है, इसके छोटे आकार को देखते हुए, विशेष रूप से साफ कोड के साथ युग्मित किया गया है, कि आप कोड को तलाशने वाले सभी भविष्य के रखवालों की तुलना में अधिक समय प्रलेखन लिखने में बिताएंगे।
जब कोड स्व-दस्तावेजीकरण होता है, तो कुछ डेवलपर्स के अनुसार इन-कोड डॉक्यूमेंट (कोड टिप्पणियों) की आवश्यकता नहीं होती है। उनके लिए, टिप्पणियों की उपस्थिति, दुर्लभ मामलों को छोड़कर, एक अच्छा संकेत नहीं है, लेकिन एक संकेत है कि कोड को टिप्पणियों की आवश्यकता के बिना स्पष्ट होने के लिए पर्याप्त रूप से अस्वीकार नहीं किया गया था।
मुझे लगता है कि किसी प्रोजेक्ट के डिलीवर होने के बाद हमें डॉक्यूमेंटेशन रिव्यू करना चाहिए।
यदि आपका प्रोजेक्ट प्रति सप्ताह कम से कम एक बार दिया जाता है, तो यह जाने का तरीका है। यदि आपकी परियोजना चुस्त नहीं है और छह महीने के अंतराल पर वितरित की जाती है, तो अधिक नियमित समीक्षा करें।