😨 🍠 ☝🏻 नमस्कार, मेरा नाम SiTLar है, मैं 30 साल का हूँ और मैं स्वयं-दस्तावेज कोड लिख रहा हूँ 👩🏿‍🚒 🛀🏼 🔔

मुझे लंबे समय से कोड टिप्पणी करने के विषय में दिलचस्पी है। यह पोस्ट मेरे लिए अपने कोड प्रलेखन विचारधारा को औपचारिक बनाने के लिए एक उपलब्धि है।

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

मैंने संयोग से शब्द "सभी विवरणों का वर्णन" लिखा था, क्योंकि यह लगभग वैसा ही है

std::map<std::string, Person*>mapPPersonsNames //map person pointers by names

मुझे ऐसे विधर्मी जीवन की प्राप्ति कैसे हुई?

जब मैं छोटा था, मैंने क्विक बेसिक और REXX में प्रोग्राम करना सीखा। मैं वैरिएबल ए, एए, एक्स 1 नाम देने के लिए तिरस्कार नहीं करता था। फिर यह मेरे लिए स्पष्ट हो गया कि यह निश्चित रूप से एक बुरा विचार था, क्योंकि अगले दिन कुछ भी स्पष्ट नहीं था। मैंने चर को थोड़ा और सार्थक रूप से नाम देना शुरू किया, उदाहरण के लिए, पैसे, उत्तर, file_count। कुछ बिंदु पर, मैंने ओएस / 2 के लिए एक पीटो स्विचर प्रोग्राम करने का निर्णय लिया। स्वाभाविक रूप से, मुझे एपीआई सीखना था और यहाँ मैं वास्तव में स्व-दस्तावेज कोड की भावना से प्रेरित था। ओएस / 2 एपीआई में चर और कार्यों के नाम इतने विस्तृत हैं कि कभी-कभी विवरण पढ़ने के लिए भी आवश्यक नहीं था। यह देखने के लिए पर्याप्त था कि उन्होंने मापदंडों को कैसे चिह्नित किया। मेरे लिए यह विचार आया कि क्यों न टिप्पणियों से सारी जानकारी सीधे कोड में स्थानांतरित की जाए?

आपको कोड में टिप्पणियों की आवश्यकता क्यों है?

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

मैं स्व-दस्तावेज कोड लिखता हूं क्योंकि मैं दोहरे काम पर समय नहीं बिताना चाहता।

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

... यहाँ लूप काउंटर i_1 बनाना आवश्यक होगा, क्योंकि बाहरी लूप i ...
धिक्कार है! i_1 पंक्ति द्वारा पंक्ति नहीं बल्कि स्तंभ द्वारा है ...

क्या यह स्थिति परिचित है? मुझे आशा है कि नहीं, क्योंकि uiRowCount और uiColCount पर लूप के चारों ओर जाना मुश्किल नहीं है। लेकिन इस मामले में, इन चर के विवरण में अर्थ गायब हो जाता है।

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

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

लेकिन पुस्तकालयों का क्या?

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

अप्रिय स्थिति, सही? उसी समय, एक अलग फ़ाइल बायनेरिज़ के साथ वितरित की जाएगी और उपयोगकर्ता केवल धन्यवाद कहेगा। वैसे, वास्तुकला या वर्ग पदानुक्रम का वर्णन करने के लिए समान है। यदि जटिल श्रृंखलाएं हैं, तो उन्हें एक अलग फाइल में क्यों नहीं बताया गया है?

युपीडी

समुदाय के अनुरोध पर मैं एक उदाहरण कोड देता हूं।

 struct HGenStuff: public std::unary_function<const std::pair<wxString,int>&, void>{ std::map<wxString, DevDesc*>& mapDevs; std::map<wxString, LogDesc*>& mapLogs; HandlerLibData & hData; HGenStuff(std::map<wxString, DevDesc*>&_mapDevs, std::map<wxString, LogDesc*>&_mapLogs,HandlerLibData&_hData): mapDevs(_mapDevs), mapLogs(_mapLogs), hData(_hData) {}; inline void operator()(const std::pair<wxString,TypeFlag>&paInp){ if(paInp.second.isSet(HandlerLibData::DEVICE)){ std::map<std::string,DevInterface*>::iterator itDev; if((itDev = hData.HLI.mapDevs.find(std::string(paInp.first.mb_str())))!=hData.HLI.mapDevs.end()){ mapDevs.insert(std::make_pair(paInp.first, new DevDesc(itDev->second, &hData))); } } if(paInp.second.isSet(HandlerLibData::LOGGER)){ std::map<std::string,Logger *>::iterator itLog; if((itLog = hData.HLI.mapLogs.find(std::string(paInp.first.mb_str())))!=hData.HLI.mapLogs.end()){ mapLogs.insert(std::make_pair(paInp.first, new LogDesc(itLog->second, &hData))); } } } }; struct HandlerActivator: public std::unary_function<HandlerLibData&, void>{ HandlerBroker *pHB; std::map<wxString, DevDesc*>mapDevs; std::map<wxString, LogDesc*>mapLogs; std::map<wxString,std::map<wxString,TypeFlag> > &toUse; bool &bSuccess; HandlerActivator(HandlerBroker *_pHB, std::map<wxString,std::map<wxString,TypeFlag> > &_toUse, bool &_bSuccess):pHB(_pHB), toUse(_toUse), bSuccess(_bSuccess){ }; inline void operator()(HandlerLibData&inp){ std::map<wxString,std::map<wxString,TypeFlag> >::iterator it(toUse.find(inp.md5)); if(it != toUse.end()) std::for_each(it->second.begin(),it->second.end(),HGenStuff(mapDevs,mapLogs , inp)); } ~HandlerActivator(){ if (!pHB->checkLock(mapDevs)) bSuccess = wxYES == wxMessageBox(wxT("Some locks seam to be incompatible. Shall we use new device handlers selection?\n"),wxT("Confirm"), wxYES_NO | wxICON_EXCLAMATION ); if(bSuccess ) pHB->setAvailHandlers(mapDevs, mapLogs); }; }; bool MyFrame::pocessHandlers(std::map<wxString, std::map<wxString,TypeFlag> > &mapHandlersToUse){ std::set<HandlerLibData>::iterator it = strIntConf.setHandlerLibs.begin(); std::set<HandlerLibData>::iterator itEnd = strIntConf.setHandlerLibs.end(); bool bSuccess = true; HandlerActivator hGen(fGetHBroker(),mapHandlersToUse, bSuccess); while(it != itEnd) hGen(*const_cast<HandlerLibData*>(&(*it++))); return bSuccess; } void MyFrame::loadHandlers(){ wxDynamicLibrary dllDev; wxDir dirHandlers(strIntConf.sHandlersDir); wxString sLibName; if (!dirHandlers.GetFirst( &sLibName, wxEmptyString, wxDIR_FILES)) return; do { MD5 md5Op; wxString sFullPath = strIntConf.sHandlersDir + wxFileName::GetPathSeparator() +sLibName; wxString md5 = wxString(md5Op.digestFile((sFullPath).mb_str(wxConvLibc)),wxConvUTF8 ); if (strIntConf.setHandlerLibs.find(HandlerLibData(md5))!=strIntConf.setHandlerLibs.end()) continue; if(!dllDev.Load( sFullPath )) wxLogError(wxString::Format(wxT("Error Loading ")) + sLibName); else{ void (*dynLoad)(HandlerLibInterface *) = reinterpret_cast<void (*)(HandlerLibInterface* )>(dllDev.GetSymbol(wxT("dynLoad"))); if(dynLoad) { HandlerLibInterface HLI; dynLoad(&HLI); strIntConf.setHandlerLibs.insert( HandlerLibData( md5, sLibName, strIntConf.sHandlersDir, HLI,dllDev.Detach())); }else dllDev.Unload(); } }while(dirHandlers.GetNext( &sLibName)); }

नमस्कार, मेरा नाम SiTLar है, मैं 30 साल का हूँ और मैं स्वयं-दस्तावेज कोड लिख रहा हूँ

मुझे ऐसे विधर्मी जीवन की प्राप्ति कैसे हुई?

आपको कोड में टिप्पणियों की आवश्यकता क्यों है?

मैं स्व-दस्तावेज कोड लिखता हूं क्योंकि मैं दोहरे काम पर समय नहीं बिताना चाहता।

लेकिन पुस्तकालयों का क्या?

More articles: