टिप्पणियां कब "बहुत अधिक" हैं, और जब वे पर्याप्त नहीं हैं?

Question

एक मामूली मामूली बहस है जहां मैं कोड के भीतर टिप्पणियों की प्रभावकारिता के बारे में काम करता हूं। लीडों में से एक ने अपने डेवलपर्स को टिप्पणियों का उपयोग न करने का निर्देश दिया क्योंकि वे बहुत पुराने हैं "और कुछ अन्य डेवलपर्स ने संकेत दिया कि वे कभी भी टिप्पणियों का उपयोग नहीं करते क्योंकि उन्हें लगता है कि वे जो भी करते हैं, वे कोड को अव्यवस्थित करते हैं।

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

स्पष्ट रूप से यह व्यक्तिपरक है, लेकिन मुझे यह जानकर उत्सुकता है कि किसी के पास किसी भी तरह से या वास्तव में किसी भी तरह के अच्छे तर्क या अनुभव हैं।

Answer 1

इस पर मौत पर चर्चा की गई है।

मैं आपको केवल Jeff Atwood's wonderful post on the subject पर इंगित करूंगा, जो सिर पर नाखून को सीधे हिट करता है।

Answer 2

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

सामान्य मामले में, केवल वास्तव में महान कोड गुरु इस तरह के कोड लिखते हैं। हममें से बाकी कुछ काम करता है जो काम करता है।

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

Answer 3

टिप्पणियों के साथ समस्या यह है कि वे उस कोड के बाद लंबे समय तक रहना चाहते हैं जिस पर टिप्पणी की गई है या यहां तक ​​कि हटा दिया गया है।

अंगूठे के नियम के रूप में मैं केवल सार्वजनिक एपीआई पर टिप्पणी करता हूं और एल्गोरिदम को समझना मुश्किल होता हूं।

आपके द्वारा किए गए कार्यों को समझाने के लिए टिप्पणियों का उपयोग न करें - यही कोड है, यह समझाने के लिए टिप्पणियों का उपयोग करें कि आपने ऐसा क्यों किया।

Answer 4

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

Answer 5

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

Answer 6

मेरे सभी करियर में, मैं उस अद्भुत जानवर "स्वयं-दस्तावेज़ कोड" में कभी नहीं आया हूं। हो सकता है कि मैं अभी दुर्भाग्यपूर्ण रहा हूं, लेकिन मुझे संदेह है कि यह वास्तव में अस्तित्व में नहीं है।

Answer 7

"लीड्स में से एक ने अपने डेवलपर्स को टिप्पणियों का उपयोग न करने के निर्देश दिए क्योंकि वे भी" पुराने फैशन "हैं, और कुछ अन्य डेवलपर्स ने संकेत दिया कि वे कभी भी टिप्पणियों का उपयोग नहीं करते क्योंकि उन्हें लगता है कि वे जो भी करते हैं, वे कोड को अव्यवस्थित करते हैं।"

यदि मैंने कभी एक डेवलपर सुना है तो मैं इस तरह की बात के साथ काम कर रहा था, मैं उन्हें सही कर दूंगा। अगर मेरे पास उन्हें सही करने के लिए आवश्यक रैंक नहीं था, तो मैं नौकरी छोड़ दूंगा।

अच्छी पहचानकर्ताओं के साथ बहुत स्पष्ट रूप से लिखित कोड - सामान को कभी-कभी 'स्वयं-दस्तावेज' के रूप में संदर्भित किया जाता है - यह बताता है कि कोड क्या कर रहा है। जहां तक ​​यह जाता है ठीक है। टिप्पणियों का काम क्यों समझाया जाना है।

Answer 8

यह विषय एक बहुत विचार-विमर्श किया जाता है, लेकिन यहाँ मेरी अमेरिका विषय पर $ 0.02 कर रहे हैं:

1. मैं नहीं बल्कि पर्याप्त नहीं की तुलना में बहुत अधिक टिप्पणियां देखना होगा। किसी भी चीज़ पर विफल होना, आप हमेशा कोड से अनावश्यक टिप्पणियां हटा सकते हैं; हालांकि, यदि आप वहां से कोई भी शुरुआत नहीं कर रहे हैं तो आप उनसे अर्थ नहीं प्राप्त कर सकते हैं।
2. मैंने सुना है कि कुछ डेवलपर्स तर्क देते हैं कि अन्य दस्तावेज जो "दस्तावेज़ पर" (इसकी परिभाषाएं व्यक्ति द्वारा अलग-अलग होती हैं) उनके कोड अच्छे डेवलपर्स नहीं हैं। यह कहकर कि आप एक काउंटर अपडेट कर रहे हैं, यह संकेत हो सकता है कि आप नहीं जानते कि आप क्या कर रहे हैं, जिस तरीके से आप काम कर रहे हैं, उसके बीच में बैठे कुछ व्यावसायिक तर्कों के लिए एक स्पष्ट मार्गदर्शिका हो सकती है।
3. हालांकि वहां कुछ उत्कृष्ट डेवलपर्स हैं जो अत्यंत स्पष्ट कोड लिख सकते हैं जिनके लिए टिप्पणियों की आवश्यकता नहीं होती है, अधिकांश डेवलपर्स अच्छे नहीं होते हैं या वे स्वयं को दस्तावेज लिखने के लिए कोड लिखने में अधिक समय बिताते हैं, अगर वे सिर्फ कुछ टिप्पणियां शामिल
4. आप अपने कोड को पढ़ने के लिए अगले व्यक्ति के कौशल स्तर को नहीं जानते हैं और यदि आपके द्वारा उपयोग की जाने वाली भाषा संरचना भ्रमित हो सकती है तो यह आमतौर पर एक टिप्पणी शामिल करना एक अच्छा विचार है कि कोई Google के साथ एक ट्यूटोरियल का उपयोग कर सकता है।

Answer 9

Diomidis Spinellis सिर्फ आईईईई स्तंभ (quoted on his blog) के लिए एक अच्छी कॉलम लिखा है, समस्या की रूपरेखा, और कुछ समाधान:

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