कभी-कभी यह तय करना मुश्किल होता है कि आपने अपने इरादे को समझने के लिए किसी के लिए पर्याप्त टिप्पणियां कब लिखी हैं।कोड में अधिक टिप्पणियां या बस सरल, पठनीय, रखरखाव कोड पर्याप्त हैं?
मुझे लगता है कि किसी को पढ़ने के लिए आसानी से ध्यान केंद्रित करने की आवश्यकता है, जिसमें कोडों की एक बड़ी संख्या शामिल है, जिसमें टिप्पणियों की एक बड़ी संख्या शामिल है, जो हो रहा है, हर विवरण बताते हुए।
इस बारे में आपके विचार क्या हैं?
टिप्पणियां यह नहीं बताती कि आप क्या कर रहे हैं। वे यह बताने के लिए हैं कि आप इसे क्यों कर रहे हैं।
मुझे लगता है कि पर्याप्त टिप्पणी कर रही है ताकि अगर आप बाद में अपने कोड की समीक्षा कर सकें तो जीवन में पर्याप्त होना चाहिए।
मुझे लगता है कि अगर आप सभी के लिए टिप्पणी करते हैं तो बहुत समय बर्बाद हो जाएगा; और इस मार्ग पर जाने से आपका कोड समझने में भी मुश्किल हो सकता है।
मैं मानता हूं कि पठनीय कोड लिखना शायद सबसे महत्वपूर्ण हिस्सा है, लेकिन टिप्पणियां न छोड़ें। अतिरिक्त समय ले लो।
पठनीय कोड नंबर 1 प्राथमिकता होना चाहिए। टिप्पणियां हैं, जैसे पॉल टॉम्बलिन ने पहले से ही क्यों लिखा है, इस पर ध्यान केंद्रित करने के लिए।
कोड को स्वयं व्याख्या करने का प्रयास करें। कक्षाओं, कार्यों, चर आदि के लिए सार्थक नामों का उपयोग करना सबसे महत्वपूर्ण बातों में से एक है
उन अनुभागों पर टिप्पणी करें जो आत्म-व्याख्या नहीं कर रहे हैं। मामूली टिप्पणी (उदा। I ++; // i में 1 जोड़ें) कोड को पढ़ने के लिए कठिन बनाता है।
वैसे - छद्म कोड के करीब आप काम कर सकते हैं, आपके कोड को और अधिक आत्म-समझा जा सकता है। यह उच्च स्तरीय भाषाओं का विशेषाधिकार है; आत्म-समझा विधानसभा कोड बनाना मुश्किल है।
मैं जितना संभव हो टिप्पणी करने से बचने की कोशिश करता हूं। कोड आत्म व्याख्यात्मक होना चाहिए। नाम चर और तरीके सही ढंग से। उन तरीकों से बड़े कोड ब्लॉक तोड़ें जिनके पास अच्छा नाम है। उन तरीकों को लिखें जो एक चीज करते हैं, जिस चीज के लिए आपने उन्हें नाम दिया था।
यदि आपको कोई टिप्पणी लिखने की आवश्यकता है। इसे छोटा करो। मुझे अक्सर यह महसूस होता है कि अगर आपको इस कोड को ब्लॉक करने के लिए लंबे समय तक विस्तृत करने की आवश्यकता है और आपको डिजाइन के साथ पहले से ही कोई समस्या है।
मेरे अनुभव में, "कोड स्वयं व्याख्यात्मक होना चाहिए" बहुत आदर्शवादी है और यह बड़े, जटिल, बहु-डेवलपर सिस्टम तक स्केल नहीं करता है। असली दुनिया में, कभी-कभी सबसे अच्छे नाम वाले चर और फ़ंक्शंस अभी भी आपको नहीं बता सकते हैं कि कोड क्या करता है। –
मैं पूरी तरह से सहमत हूं। लेकिन वहां कई डेवलपर्स हैं जो स्वयं स्पष्टीकरण कोड लिखने की कोशिश भी नहीं करते हैं। – raupach
तर्क एक झूठी दुविधा पर आधारित है: या तो आपका कोड एक भयानक घृणा है और आप प्रत्येक कथन और अभिव्यक्ति को समझाने के लिए कई टिप्पणियां लिखते हैं, या आपका कोड सुंदर कविता है जिसे आपकी दादी द्वारा कोई दस्तावेज नहीं समझा जा सकता है सब।
हकीकत में, आपको बाद में (अच्छी तरह से, शायद अपनी दादी नहीं बल्कि अन्य डेवलपर्स) के लिए प्रयास करना चाहिए, लेकिन महसूस करें कि कई बार जब कुछ टिप्पणियां अस्पष्टता को साफ़ कर देती हैं या कोड की अगली दस पंक्तियां बनाती हैं तो बहुत अधिक सादा। पर सलाह देने वाले लोग सभी पर कोई टिप्पणी नहीं चरमपंथी हैं।
बेशक, gratuitous टिप्पणियों से बचा जाना चाहिए। कोई भी टिप्पणी खराब कोड को और समझने में मदद करेगी। वे शायद इसे और भी खराब बनाते हैं। लेकिन जब तक कि आप केवल छोटी प्रणाली को कोड नहीं कर रहे हों, ऐसे समय होंगे जब टिप्पणियां डिजाइन निर्णयों को स्पष्ट करती हैं।
यह बग पकड़ते समय सहायक हो सकता है। पूरी तरह से गलत होने पर साक्षर कोड पूरी तरह से वैध दिख सकता है।टिप्पणियों के बिना, अन्य (या आप छह महीने बाद) को अपने इरादे के बारे में अनुमान लगाना पड़ता है: क्या आपका मतलब यह था, या यह एक दुर्घटना थी? क्या यह बग है, या यह कहीं और है? शायद मुझे डिजाइन दस्तावेज का संदर्भ लेना चाहिए ... टिप्पणियां इनलाइन दस्तावेज हैं, जहां आपको इसकी आवश्यकता है वहां दिखाई दे रहा है।
उचित निर्णय लेने पर वास्तव में निर्णय लेने की आवश्यकता महत्वपूर्ण है।
+ यदि मैं कर सकता तो अधिक :) –
सहमत हुए। जब भी मैं किसी को यह कहता हूं कि केवल बुरे कोड में टिप्पणियां हैं, मुझे लगता है कि यह स्पष्ट रूप से कोई है जिसने कभी बड़े, जटिल, उत्पादन प्रणाली के लिए कोड नहीं लिखा है। –
आपको टिप्पणियों की आवश्यकता क्यों है। विधि का नाम इतना स्पष्ट होना चाहिए कि आपको टिप्पणियों की आवश्यकता नहीं है।
पूर्व:
// This method is used to retrieve information about contact
public getContact()
{
}
इस मामले में getContact टिप्पणी
नहीं सभी कोड आत्म दस्तावेज़ीकृत कर रहा है की जरूरत नहीं है।
मैं अब एक प्रदर्शन समस्या निवारण की प्रक्रिया में हूं। डेवलपर ने सोचा कि उसने बाधा के स्रोत की खोज की है; कोड का एक ब्लॉक जो किसी कारण से सो रहा था। इस कोड के आसपास कोई टिप्पणी नहीं थी, के संदर्भ में कोई सन्दर्भ क्यों नहीं था यह वहां था। हमने ब्लॉक को हटा दिया और पुनः परीक्षण किया। अब, ऐप लोड के तहत असफल रहा है जहां यह पहले नहीं था।
मेरा अनुमान है कि किसी ने पहले प्रदर्शन प्रदर्शन में भाग लिया था और इस कोड को समस्या को कम करने के लिए रखा था। सही समाधान था या नहीं, यह एक बात है, लेकिन के बारे में कुछ टिप्पणियां क्यों यह कोड अब हमें दर्द की दुनिया और पूरे समय की बचत कर रहा है ...
केवल टिप्पणी करें जब यह टिप्पणी करें कुछ जोड़ता है
कुछ इस तरह बेकार है और निश्चित रूप से पठनीयता कम हो जाती है: कोई टिप्पणी नहीं की जरूरत है, लेकिन अपने आप को बहुत ज्यादा है, तो तुम्हें याद हराते नहीं हैं कोड के लिए
/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
उद्देश्य।
मूल रूप से, एक वर्ग/विधि/समारोह घोषणा की शुरुआत में एक अच्छी लेकिन संभवतः संक्षिप्त टिप्पणी को छोड़कर, और - यदि आवश्यक हो - फ़ाइल की शुरुआत में एक प्रारंभिक टिप्पणी, एक टिप्पणी उपयोगी होगी जब एक गैर- इतना आम या स्पष्ट रूप से पारदर्शी ऑपरेशन कोडित नहीं है।
तो, उदाहरण के लिए, आपको स्पष्ट (i ++; पिछले उदाहरण पर) टिप्पणी करने से बचना चाहिए, लेकिन जो आप जानते हैं वह कम स्पष्ट और/या अधिक मुश्किल है, कुछ स्पष्ट, अप्रचलित, शानदार, टिप्पणी की पूरी पंक्ति के लायक होना चाहिए, जो इतिहास में सबसे स्पष्ट कोड के लिए स्वाभाविक रूप से नोबेल पुरस्कार के साथ आता है;)।
और इस तथ्य को कम मत समझें कि एक टिप्पणी भी मजाकिया होनी चाहिए; यदि आप बौद्धिक रूप से उन्हें परेशान कर सकते हैं तो प्रोग्रामर अधिक खुशी से पढ़ते हैं।
इसलिए, एक सामान्य सिद्धांत के रूप में टिप्पणी के साथ जबरदस्त नहीं होता है, लेकिन जब आपको एक लिखना होता है, तो सुनिश्चित करें कि यह स्पष्ट टिप्पणी हो सकती है जिसे आप लिख सकते हैं।
और व्यक्तिगत रूप से मैं स्वयं-दस्तावेज़ कोड (उर्फ कोड डब्ल्यू/ओए सिंगल डॉन स्लैशस्टार) का बड़ा प्रशंसक नहीं हूं: महीनों के बाद आपने इसे लिखा है (यह मेरे व्यक्तिगत पैमाने के लिए सिर्फ दिन है) यह बहुत संभव है कि आप इस तरह के डिजाइन को चुनने के लिए सही कारण बताएं कि आपकी बुद्धि के टुकड़े का प्रतिनिधित्व करने के लिए, तो दूसरों को कैसे?
टिप्पणियां कोड लाइनों के बीच केवल हरी सामग्री नहीं हैं; वे कोड का हिस्सा हैं जो आपका दिमाग संकलित करने के लिए बेहतर है। मस्तिष्क कोड (हंसी) के रूप में योग्यता मैं टिप्पणियों की पुष्टि नहीं कर सकता कि आप जो प्रोग्राम लिख रहे हैं उसका हिस्सा नहीं हैं। वे केवल इसका हिस्सा हैं जो सीपीयू को निर्देशित नहीं है।
आम तौर पर, मैं प्रलेखन टिप्पणियों का प्रशंसक हूं जो स्पष्ट रूप से आपके द्वारा लिखे गए कोड के इरादे को स्पष्ट करता है। एनडीओसी और सैंडकासल जैसे स्पिफी टूल एक अच्छा, सुसंगत तरीका प्रदान करते हैं जिसमें उस दस्तावेज़ को लिखना है।
हालांकि, मैंने पिछले कुछ वर्षों में कुछ चीजें देखी हैं।
अधिकांश दस्तावेज टिप्पणियां वास्तव में मुझे कुछ भी नहीं बताती हैं, मैं वास्तव में कोड से नहीं मिल सकता। यह निश्चित रूप से मानता है कि मैं स्रोत कोड से शुरू करने के लिए सिर या पूंछ बना सकता हूं।
टिप्पणियां इरादे, व्यवहार नहीं करने के लिए उपयोग की जाने वाली हैं। दुर्भाग्य से, अधिकांश मामलों में, ऐसा नहीं है कि उनका उपयोग कैसे किया जाता है। एनडीओसी और सैंडकैसल जैसे टूल्स केवल टैग्स का भरपूर उपयोग करके टिप्पणियों के गलत उपयोग का प्रचार करते हैं जो आपको टिप्पणियां प्रदान करने के लिए प्रोत्साहित करते हैं जो पाठक चीजों को बताते हैं कि उन्हें कोड से ही समझने में सक्षम होना चाहिए।
समय के साथ, टिप्पणियां कोड के साथ समन्वयित हो जाती हैं। यह इस बात पर ध्यान दिए बिना कि हम दस्तावेज़ीकरण सॉफ्टवेयर का उपयोग कर रहे हैं या नहीं, जो दस्तावेज़ीकरण को आसान बनाने के लिए कहता है क्योंकि यह दस्तावेज को उस कोड के करीब रखता है जो इसका वर्णन करता है। भले ही प्रलेखन विधि, संपत्ति, घटना, कक्षा या अन्य प्रकार के बगल में है, डेवलपर्स को अभी भी इसे अद्यतन करने के लिए याद रखने में कठिनाई होती है, जब आंतरिक व्यवहार बदलता है। नतीजतन, दस्तावेज इसके मूल्य खो देता है।
यह ध्यान देने योग्य है कि टिप्पणियों के दुरुपयोग के कारण ये समस्याएं बड़े पैमाने पर हैं। यदि टिप्पणी पूरी तरह से इरादे को व्यक्त करने के साधन के रूप में उपयोग की जाती है, तो ये समस्याएं डोडो के रास्ते पर जाती हैं, क्योंकि किसी दिए गए प्रकार या उसके सदस्यों के इरादे से समय के साथ बदलने की संभावना नहीं है। (यदि ऐसा होता है, तो एक बेहतर योजना है कि एक नया सदस्य लिखना और पुराने को एक के संदर्भ में पुराना छोड़ दें।)
टिप्पणियों का उचित मूल्य हो सकता है यदि उनका उपयोग ठीक से किया जाता है। लेकिन इसका मतलब यह है कि वे किस चीज के लिए सबसे अच्छे इस्तेमाल करते हैं, और उस क्षेत्र में उनके उपयोग को बाधित करते हैं। यदि आप ऐसा करने में असफल होते हैं, तो आप जो कुछ भी समाप्त करते हैं, वह गलत है, भ्रामक है, और व्यस्त कार्य का स्रोत (बढ़ी हुई लागत पर) क्योंकि अब आपको उन्हें हटा देना है या किसी भी तरह उन्हें सही करना है।
यह एक सार्थक तरीके से टिप्पणियों का उपयोग करने की रणनीति रखने के लिए योग्य है जो उन्हें समय, ऊर्जा और धन सिंक बनने से रोकता है।
अध्ययनों ने कहा है कि इष्टतम पठनीयता तब होती है जब आपके पास कोड की 10 पंक्तियों के लिए टिप्पणियों की लगभग 1 पंक्ति होती है। बेशक, यह कहना नहीं है कि अगर आप आगे बढ़ते हैं तो आपको अपने राशन को 1/10 और आतंक में रखना होगा। लेकिन यह आपको एक विचार देने का एक अच्छा तरीका है कि आपको कितना टिप्पणी करनी चाहिए।
यह भी याद रखें कि टिप्पणियां कोड गंध हैं। यही कहना है कि वे खराब कोड का संकेतक हो सकते हैं लेकिन ऐसा नहीं हैं। इसका कारण यह है कि कोड को समझना अधिक कठिन है और अधिक टिप्पणी की गई है।
पूरी तरह से सच नहीं है (उदाहरण के लिए जब आप मुश्किल कोड लिख रहे हैं, जैसे बिट ट्विडलिंग हैक्स) लेकिन +1 परवाह किए बिना। – strager
कोई भी हर किसी के पहले असेंबलर प्रोग्राम को याद करता है, जहां आप मूल रूप से निर्देश को प्रतिबिंबित करने वाली प्रत्येक पंक्ति पर एक टिप्पणी करेंगे? "टैक्स; एक्स्यूम्युलेटर को एक्स में स्थानांतरित करें" –
लॉल, yup क्योंकि असेंबलर कठिन था और हमें हर टिप्पणी पर टिप्पणी करना पड़ा ;-)। –