दस्तावेज़ीकरण विरासत कोड-बेस
मैं विरासत कोड-ठिकानों के साथ स्काउट नियम का पालन करने की अत्यधिक सलाह दूंगा। स्वतंत्र रूप से उस पर काम करने के लिए एक विरासत परियोजना का दस्तावेजीकरण करने की कोशिश सिर्फ कभी नहीं होगी।
इन-कोड प्रलेखन
सबसे महत्वपूर्ण बात यह है कि आपके चुने हुए विकास के माहौल में प्रलेखन सुविधाओं का उपयोग करना है, इसलिए इसका अर्थ है कि python के लिए pydoc , जावा में javadoc या C # में xml टिप्पणियाँ । ये कोड लिखने के साथ ही प्रलेखन लिखना आसान बनाते हैं।
यदि आप बाद में वापस आने और चीजों के दस्तावेजीकरण पर भरोसा करते हैं, तो आप इसके आस-पास नहीं पहुंच सकते हैं, लेकिन यदि आप इसे वैसे ही कर रहे हैं जैसे आप कोड लिख रहे हैं, तो आपको जो दस्तावेज बनाने की आवश्यकता है वह आपके दिमाग में ताजा होगी। यहां तक कि अगर XML प्रलेखन वास्तविक कोड के साथ अपूर्ण या असंगत है, तो संकलन चेतावनी जारी करने का विकल्प भी है।
प्रलेखन के रूप में परीक्षण
एक अन्य महत्वपूर्ण पहलू अच्छा एकीकरण और इकाई परीक्षण है।
अक्सर दस्तावेज़ीकरण इस बात पर ध्यान केंद्रित करता है कि किस वर्ग और विधियां अलगाव में हैं, आपकी समस्या को हल करने के लिए उन्हें एक साथ कैसे उपयोग किया जाता है। टेस्ट अक्सर उन्हें संदर्भ में दिखाते हैं कि वे एक-दूसरे के साथ कैसे बातचीत करते हैं।
इसी तरह, यूनिट-परीक्षण अक्सर बाहरी निर्भरता को स्पष्ट रूप से इंगित करते हैं जिसके माध्यम से चीजों को मॉक एड आउट करने की आवश्यकता होती है ।
मुझे यह भी पता चलता है कि टेस्ट-संचालित विकास का उपयोग करके मैं सॉफ्टवेयर लिखता हूं जो उपयोग करना आसान है, क्योंकि मैं इसे शब्द से सही उपयोग कर रहा हूं। एक अच्छे परीक्षण ढांचे के साथ, कोड को परीक्षण करना आसान बना देता है और इसका उपयोग करना आसान बना देता है।
उच्च स्तरीय प्रलेखन
अंत में सिस्टम स्तर और वास्तु प्रलेखन के बारे में क्या करना है। कई ऐसे दस्तावेज़ को विकी में लिखने या वर्ड या अन्य वर्ड प्रोसेसर का उपयोग करने की वकालत करेंगे, लेकिन मेरे लिए इस तरह के प्रलेखन के लिए सबसे अच्छी जगह कोड के साथ, एक सादे पाठ प्रारूप में भी है जो संस्करण नियंत्रण प्रणाली के अनुकूल है।
इन-कोड डॉक्यूमेंटेशन की तरह ही, यदि आप अपने कोड रिपॉजिटरी में अपने उच्च स्तर के डॉक्यूमेंट को स्टोर करते हैं, तो आपको इसे अपडेट रखने की संभावना है। आपको यह भी लाभ मिलता है कि जब आप कोड के संस्करण XY को निकालते हैं, तो आपको प्रलेखन के XY संस्करण भी मिलते हैं। इसके अलावा, यदि आप वीसीएस के अनुकूल प्रारूप का उपयोग करते हैं, तो इसका मतलब है कि यह आपके कोड की तरह ही शाखा, अंतर और मर्ज करना आसान है।
मैं rst को काफी पसंद करता हूं , क्योंकि इसमें html पेज और पीडीएफ़ दोनों दस्तावेज़ों का उत्पादन करना आसान है, और LaTeX की तुलना में बहुत अधिक मैत्रीपूर्ण है , फिर भी आपको आवश्यकता पड़ने पर अभी भी LaTeX गणित के भावों को शामिल कर सकते हैं।