कोड में टिप्पणियों के बारे में, एक शब्द में रखें

टिप्पणियों में एक पोस्ट थी, जिसमें (क्या विडंबना थी) कई राय थीं,
सबसे अच्छा कोड है स्व-दस्तावेजीकरण और वह सब।

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


एक पोस्ट में मैं संक्षेप में बताऊंगा कि कैसे मैं 10 वर्षों से अपने विकास में टिप्पणियों का उपयोग कर रहा हूं और सामान्य रूप से प्रलेखन के विषय पर आसानी से स्पर्श करूंगा।

टिप्पणियां आपको अपना भूला हुआ कोड ढूंढने में मदद करती हैं।

Artemy Lebedev (चौंकाने वाले IMHO के मास्टर) का ऐसा नियम है - वह उनके सोचने का तरीका जानता है। और अगर आप कुछ भूल जाते हैं, उदाहरण के लिए, जहां वांछित फोटो निहित है, तो अपने वर्गीकरण प्रणाली को जानने से आप सही फोटो को जल्दी से ढूंढ सकते हैं।

टिप्पणियों के साथ एक ही बात। मेरे पास ऐसे प्रोजेक्ट हैं जिन्हें मैंने कई सालों से नहीं छुआ है। आप इस परियोजना को IDE में खोलते हैं, कुछ शब्दों को ड्राइव करते हैं, और आवश्यक फाइलों और कक्षाओं को सहजता से पाते हैं। यही है, पहला विषय यह है कि कम से कम हर फ़ाइल क्या लिखना है, बहुत शुरुआत में। यह आपको बहुत खोज समय बचाता है। और जब परीक्षण भी होते हैं - तो खोज पूरी तरह से सरल हो जाती है।

टिप्पणियाँ IDE में विकसित करने में मदद करती हैं

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

टिप्पणियाँ दस्तावेज़ बनाने में मदद करती हैं

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

सामान्य रूप में प्रलेखन

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

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

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

छह महीने बाद, मैंने ट्यूटोरियल और एफएक्यू के लिंक के साथ 80% उत्तर दिए और स्ट्रीम को नहीं छोड़ा , हालांकि परियोजनाओं पर मेरे अधीनस्थों की संख्या दो से पांच हो गई।

निष्कर्ष

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

आप अच्छा पठनीय कोड लिख सकते हैं, लेकिन इस परियोजना को संपूर्ण मानने और ऊपर उल्लिखित व्यावहारिक समस्याओं को हल करने के लिए टिप्पणियां उपयोगी हैं।

यदि आप एक टीम में काम करते हैं, तो आपके पास ऐसी परियोजनाएं हैं जो कोड की 100,000 पंक्तियों तक बढ़ती हैं, और आप कुछ वर्षों में उनके पास वापस आएंगे - आपको केवल टिप्पणियों की आवश्यकता है। कम से कम इस या उस फ़ाइल के स्तर पर, यह या उस बड़े महत्वपूर्ण तर्क का टुकड़ा।

और हां, डैनिग-क्रुएगर प्रभाव के बारे में मत भूलना। एक व्यक्ति अपने कोड को पठनीय और समझने योग्य समझ सकता है, लेकिन इस तथ्य से नहीं कि यह दूसरों के लिए ऐसा है।

यह विशेष रूप से महत्वपूर्ण है कि नोब्स से परियोजनाओं को स्वीकार करने के बाद, जिन्होंने स्व-दस्तावेजीकरण कोड के बारे में मैककॉनेल को पढ़ा और याद किया कि आपको टिप्पणी लिखने की आवश्यकता नहीं है, और कोड और कोड सम्मेलनों को डिजाइन करने के लिए अन्य सभी सिफारिशों को नजरअंदाज कर दिया - या, भगवान ने पिछले हिंदू से एक स्वतंत्र आदेश का पालन किया साइट)।

और अगर एक ही समय में आप एक वरिष्ठ, टीम लीड डेवलपर हैं, और आपकी जिम्मेदारियों में गैर-तकनीकी लोगों के साथ काम करना शामिल है, या नए लोगों के साथ काम करना शामिल है, तो प्रलेखन को बढ़ाने की मांग के विकासवादी सिद्धांत पर बनाया जा रहा है, इसलिए बोलने के लिए, कैश हिट raio, आपके समय की महत्वपूर्ण बचत होगी।

विषय के लिंक
1. सेल्फ-डॉक्यूमेंटिंग कोड जैसी कोई चीज नहीं है - यह एक मिथक है

2. फूला हुआ नाम, और स्व-दस्तावेजीकरण कोड का मिथक

3. आशय बनाम कार्रवाई, या स्व-दस्तावेजीकरण कोड का मिथक

4. स्व दस्तावेज कोड और अन्य मिथक