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