टिप्पणियों के उदाहरण क्या हैं जो आपको बताते हैं कि इसके बजाय कैसे या क्या? [बन्द है]

Question

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

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

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

इस पर कई सवाल हैं कि क्या टिप्पणी अच्छी है या बुरी, लेकिन कोई भी व्यक्ति उस विशिष्ट प्रश्न को संबोधित नहीं करता है जो टिप्पणियों के अच्छे उदाहरण हैं जो आपको बताते हैं।

Comments

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

— Dan Pichelman

There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY. यदि हर कोई एक वैध उदाहरण प्रदान करता है, तो वे सभी सही उत्तर हैं। इस वेबसाइट का प्रारूप एक प्रश्नोत्तर प्रक्रिया को सुगम बनाना है जहां सभी उत्तर समान नहीं बनाए जाते हैं।

— डेविड कैक्ज़िनस्की

अच्छी बात है, @ दाविद- kaczynski। आपकी क्या सलाह है?

— रिक

मेरे सिर के ऊपर से, मैं प्रश्न को वाक्यांश करने का एक तरीका नहीं सोच सकता, ताकि एक भी उदाहरण या सामान्यीकृत रणनीति "सर्वश्रेष्ठ" उत्तर हो सके। P.se का एक चैट भाग है: chat.stackexchange.com/rooms/21/the-whiteboard , लेकिन आपके प्रश्न के लिए वहाँ एक बेहतर मंच होगा जैसा कि यह है। सभी निष्पक्षता में, ऐसा लगता है कि आपका प्रश्न यहां समुदाय से सकारात्मक प्रतिक्रिया प्राप्त कर रहा है, इसलिए यह संभवतः चिंता करने योग्य नहीं है। सलाह का सबसे अच्छा टुकड़ा मैं उपयोगी टिप्पणियों के उदाहरण खोजने के लिए दे सकता हूं लोकप्रिय सार्वजनिक गिट रिपॉजिटरी ब्राउज़ कर रहा होगा।

— डेविड कैक्ज़िनस्की

Answer 1

सबसे आम और सबसे विशिष्ट उदाहरण विभिन्न वर्कअराउंड के आसपास की टिप्पणियां हैं। उदाहरण के लिए यह एक:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

आपको निश्चित रूप से Git और Linux स्रोतों में अधिक उदाहरण मिलेंगे; दोनों परियोजनाएं इस नियम का पालन करने का प्रयास करती हैं।

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

इस कमिट में उदाहरण देखें । (यहां नकल नहीं हो रही है, यह बहुत लंबा है)। इसमें चार पैराग्राफ हैं जो लगभग पूरे पृष्ठ (और स्क्रीन पर थोड़ा सा) का वर्णन करते हुए बताते हैं कि वास्तव में क्या गलत था और क्यों गलत था और पूरी तरह से SIX लाइनों को संशोधित करता है। वे दो उद्देश्यों के लिए इस तरह की टिप्पणियों का उपयोग करते हैं:

1. सभी सबमिट किए गए परिवर्तनों की समीक्षा की जाती है और कमिट लॉग होता है जिसे समीक्षक को परिवर्तन की व्याख्या करनी होती है।
2. जब एक बग पाया जाता है, तो संबंधित लॉग को "पिकैक्स" या "दोष" का उपयोग करके पुनर्प्राप्त किया जाता है ताकि पहले के गलत व्यवहार पर ध्यान न दिया जा सके।

(ध्यान दें: मुझे इन दो उदाहरणों के साथ आने के लिए गिट रेपो के सबसे अधिक 10 मिनट के यादृच्छिक ब्राउज़िंग पर ले गया, इसलिए यह सुनिश्चित करना आसान होगा कि वहां और अधिक खोजें)

Answer 2

एक टिप्पणी जो आपको बताती है कि कोड के पीछे के तर्क को क्यों समझाया गया है - उदाहरण के लिए:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

एक टिप्पणी जो आपको बताती है कि कैसे समझाता है कि कोड क्या करता है।

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

अंतर यह है कि एक अनुचर पहले वाले को देख सकता है और कह सकता है, "ओह, इसलिए यह पुराना हो सकता है!" दूसरे मामले में, कहा कि अनुचर के पास एक टिप्पणी है जो आपको कुछ भी नहीं बताती है जो कोड स्वयं प्रकट नहीं करता है (अच्छा चर नाम मानते हुए)।

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

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

Comments

पहला उदाहरण अत्यधिक क्रिया है और इसमें "कैसे" शामिल है। यह जोर से कहता है कि "अपडेट करें <doodads> temp <doodad> से ताकि उपयोगकर्ता सुरक्षित रूप से <foo> जब चाहे"। बाकी यह या कोड से लागू करने के लिए तुच्छ है। साथ ही अंतिम उदाहरण के पहले चार पैराग्राफ में "परी कथा परिचय" पूरी तरह से व्यर्थ है। मैं "चिरायु ला कीचड़ छोड़ दूंगा!" यह मज़ेदार है और यह अंत में है। लेकिन शुरुआत वास्तविक व्याख्या करने से पहले बहुत सारे शब्दों को खोदने की होती है।

— जन हडेक

@JanHudec आपकी प्रतिक्रिया के अनुसार समायोजित किया गया। सही के बारे में देखो?

— thegrinner

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

— ब्रायन

Answer 3

मैं अपने ब्लॉग पोस्ट में जेफ Atwood द्वारा किए गए एक उद्धरण के साथ मेरा उत्तर शुरू करना चाहते हैं कोड आपको बताता है कि, टिप्पणियाँ बताओ तुम क्यों :

सबसे अच्छी तरह की टिप्पणी वे हैं जिनकी आपको आवश्यकता नहीं है

उन्होंने यह भी कहा कि:

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

मैं पूरी तरह से सहमत हूं और इस बिंदु पर मुझे यह जोड़ना होगा कि इससे पहले कि मैं कोड को सरल बनाना शुरू कर सकूं, मैं कोड का काम कर दूंगा और फिर रिफिलिंग शुरू कर दूंगा। इसलिए टिप्पणी जोड़ने से पहले पहले रन के दौरान टिप्पणियां बहुत मदद करती हैं।

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

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

ऊपरी एक उदाहरण है कि 3 नेस्टेड लूप कैसे फिर से तैयार करने से पहले काम करेंगे।
कुछ शाखा शर्तों की व्याख्या करने से कोड को बेहतर तरीके से समझने में मदद मिल सकती है कि प्रक्रिया में कोई क्या सोच रहा था:

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

यहां तक ​​कि सरल और स्पष्ट कोड टिप्पणियों के साथ अच्छी तरह से काम करता है। बस चीजों को थोड़ा और अधिक स्पष्ट, स्पष्ट या सहकर्मियों के लिए समझने में आसान बनाने के लिए और यहां तक ​​कि सॉफ़्टवेयर को बनाए रखने में भी।

सुनिश्चित करें कि xp में कोड है जो स्वयं की व्याख्या कर रहा है, लेकिन क्या एक पंक्ति टिप्पणी से चोट लगी है?

मुझे इस ब्लॉग से निम्नलिखित नियम भी बहुत उपयोगी लगते हैं:

• लिखने से पहले सामग्री को समझें
• लिखें जैसे कि आपका दर्शक चौथा ग्रेडर है
• इस बारे में सोचें कि पाठक आपकी गलत व्याख्या कैसे कर सकते हैं

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

समीक्षा के दौरान किए गए कई प्रोग्रामिंग डिसेक्शन पर संदेह किया जाता है और यह हमेशा स्पष्ट नहीं होता है कि कुछ हिस्सों को क्यों लिखा गया था, भले ही वे कोड के कुछ वर्गों के लिए एक प्रमुख बग के कारण काम करने के लिए महत्वपूर्ण हों, क्योंकि कोड का उपयोग वर्षों से किया गया था । तो क्रम में आप सभी एक tl के साथ पूरी तरह से बोर नहीं करने के लिए; से एक अंतिम बोली के साथ निकट डॉ acmqueue :

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

Comments

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

— क्रिस कूडमोर

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

— क्रिस कुडमोर

विज्ञापन "सुनिश्चित करें कि xp में कोड है जो स्वयं की व्याख्या कर रहा है, लेकिन क्या एक पंक्ति की टिप्पणी से चोट लगी है?": टिप्पणियाँ अच्छी हैं, लेकिन अति-टिप्पणी का भी खतरा है। टिप्पणी की प्रत्येक पंक्ति वह है जिसे कोड बदलने पर कोई व्यक्ति अपडेट करना भूल सकता है।

— Jan Hudec

यह कहने का एक बेहतर तरीका यह है कि "सबसे अच्छी तरह की टिप्पणी एक टिप्पणी की आवश्यकता का अभाव है"। जिन टिप्पणियों की आवश्यकता नहीं है (लेकिन वैसे भी लिखे गए हैं) अच्छी टिप्पणियां नहीं हैं।

— कज़

दिलचस्प है कि संदर्भित कोड int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;त्रुटि में है। निश्चित रूप से होना चाहिए ... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;। अच्छी टिप्पणी विचारों - बुरा कोड।

— chux

Answer 4

मैं टिप्पणियों को या तो उन संदर्भों में कम करता हूं जहां एक निश्चित कार्यक्षमता / कोड को अधिक अच्छी तरह से समझाया जाता है या यह समझाने के लिए कि प्रोग्रामिंग का एक निश्चित तरीका क्यों चुना जाता है।

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

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

तो 'क्यों' को अपनी पसंद के हिसाब से औचित्य देना चाहिए ।

Comments

संदर्भ एक महान उदाहरण हैं। // यह विधि फ़ॉस्बिट को पुन: व्यवस्थित करने के लिए furshclingeheimer एल्गोरिथ्म का उपयोग करती है। देखें http: // ...

— क्रिस कुडमोर

Answer 5

टिप्पणियाँ आपको बताएं कि कोड क्या नहीं है, जरूरी नहीं कि क्यों WHY , HOW , या WHAT द्वारा परिसीमन किया गया हो । यदि आपके पास अच्छे नाम हैं और अच्छी तरह से डील किए गए कार्य हैं, तो यह बहुत संभव है कि कोड आपको बता सके कि वास्तव में क्या चल रहा है। उदाहरण के लिए:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

इस कोड को वास्तव में टिप्पणियों की आवश्यकता नहीं है। फ़ंक्शन और प्रकार के नाम समझने में आसान बनाते हैं।

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

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

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

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

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

Comments

क्या कोड का वर्णन करना उचित है, जब टिप्पणियों के WriteTextबजाय टिप्पणियों की आवश्यकता होती है //?

जैसा कि मैंने उत्तर में कहा था कि यदि कोई प्रिंट स्टेटमेंट नहीं थे, तो भी टिप्पणियां अनावश्यक हैं, हालांकि मैंने बिंदु को स्पष्ट करने के लिए प्रिंट स्टेटमेंट को हटाने के लिए इसे संपादित किया है।

— Chewy Gumball

Answer 6

यह "क्यों" के विभिन्न प्रकारों को पहचानने में सहायक हो सकता है - विशेष रूप से:

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

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

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

Answer 7

मत भूलो, यदि आप एक कार्यक्रम लिख रहे हैं, तो आप केवल बेतरतीब ढंग से सामान नहीं लिख रहे हैं, आप ऐसा कर रहे हैं क्योंकि आपके पास एक मॉडल है जो आप चाहते हैं , चाहे वह एक औपचारिक दस्तावेज में हो या सिर्फ आपके सिर में हो। आपके सिर में भरा हुआ सामान कंप्यूटर में सॉफ़्टवेयर / डेटा के रूप में वास्तविक है (और सिर्फ बग को सम्‍मिलित करने के लिए)।

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

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

उसके ऊपर, समय के साथ मॉडल बदलता है, और उन परिवर्तनों को कोड में स्थानांतरित करना पड़ता है। इसलिए टिप्पणियों को न केवल "क्यों" कहने की आवश्यकता है कोड में कुछ है, लेकिन सिर्फ उतना ही महत्वपूर्ण है कि प्रत्याशित मॉडल परिवर्तनों के जवाब में इसे कैसे बदलना है । उदाहरण:

// to change to square cell locations, remove the "+ y/2" in the above code

मुझे लगता है कि टिप्पणियों के लिए उद्देश्य कभी-कभी उपेक्षित होता है।

Comments

सवाल उदाहरण के लिए पूछ रहा है। क्या आप इस उत्तर को अधिक उपयोगी बनाने के लिए एक उदाहरण जोड़ सकते हैं?

— ब्रायन ओकली

कोड का पहला हिस्सा मुझे "क्या," समझाने के एक क्लासिक उदाहरण की तरह दिखता है। ऐसा नहीं है कि यह एक बुरी टिप्पणी है, लेकिन मुझे नहीं लगता कि यह ओपी के सवाल का जवाब देता है।

@ जॉन: यदि टिप्पणी नहीं थी, तो पाठक देख सकता है कि क्या हो रहा है, लेकिन पता नहीं क्यों है।

— माइक डनलैवी

@MikeDunlavey: मैं असहमत हूं। मुझे अभी भी पता नहीं है - आप निकटतम हेक्सागोनल सेल स्थान क्यों चाहते हैं? इस स्थान को प्राप्त करने का उद्देश्य क्या है ? अगर मैं इन दो पंक्तियों को हटा दूं तो क्या यह कुछ भी प्रभावित करेगा?

Answer 8

मेरी सभी टिप्पणियाँ 'क्यों' प्रकार की नहीं हैं, लेकिन कई हैं।
ये एक (डेल्फी) स्रोत फ़ाइल से उदाहरण हैं:

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

ध्यान दें कि (मेरे) क्यों टिप्पणियां आमतौर पर कोड है कि यह करने के लिए जा रहा है पूर्व में होना (इसलिए एक कॉलन के साथ समाप्त)।

मेरे पास कुछ ऐसी टिप्पणियां हैं जो केवल यह बताती हैं कि क्या हो रहा है, उदाहरण के लिए जब एक प्रक्रिया में कई चरण होते हैं जिसमें एक तार्किक समूह होता है (और कोड को स्वचालित रूप से दिखाने के लिए फिर से तैयार नहीं किया जाता है), मैं इस तरह की टिप्पणी करूंगा:

// Step 1. Initialization

Answer 9

मैं डब्ल्यूएचवाई को इस कारण से समझता हूं कि आप संभवतः अजीब या शायद अतार्किक तरीके से कुछ करते हैं, क्योंकि दी गई परिस्थितियों के कारण ऐसा करने की आवश्यकता होती है। कैसे कोड ही है, में देखा जा सकता कोई फर्क नहीं पड़ता कि यह कैसे अजीब है, भले ही कोड नहीं "भावना" बनाता है। क्या शायद सबसे अच्छा वर्ग / समारोह प्रलेखन की शुरुआत में बताया गया है। ताकि आपको WHY को जोड़ने के साथ छोड़ दिया जाए , जहां आप HOW और WHAT में शामिल कुछ भी नहीं समझाते हैं, और अजीब तरीके जो आपको अपने नियंत्रण से परे कारणों के कारण लेने की आवश्यकता है।

बेशक यह हमेशा मामला नहीं है, गेंडा और इंद्रधनुष की भूमि के बाहर ...

किस तरह:

foreach($critters as $creature) {
   $creature->dance();
}

क्या:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

क्यों:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

Comments

यह पूछे गए प्रश्न का उत्तर कैसे देता है?

— gnat

ओपी को उद्धृत करने के लिए: "तो, इस सवाल पर वापस जाएं: यदि टिप्पणियां आपको बताएंगी कि क्यों, यह हम किस बारे में बात कर रहे हैं?" कोड का टुकड़ा दिया।

— जूहा अनटाइनन

सवाल विशेष रूप से उदाहरण के लिए एक दो बार पूछता है। क्या आप इसे अधिक उपयोगी बनाने के लिए इस उत्तर में एक उदाहरण जोड़ सकते हैं?

— ब्रायन ओकली

मुझे नहीं लगता कि इनमें से कोई भी टिप्पणी वास्तव में सहायक है। यदि आपके फ़ंक्शन का हस्ताक्षर था critters.dance(), तो टिप्पणी केवल स्पष्ट दोहराती है, और "हम इसे किसी भी अन्य तरीके से काम करने के लिए नहीं प्राप्त कर सकते हैं जो हमने कोशिश की" पूरी तरह से अनपेक्षित है। इसके अलावा, यह कहते हुए कि "हम प्रत्येक ऑब्जेक्ट के लिए विधि को कॉल करेंगे" दोहरा रहे हैं जो कोड बहुत स्पष्ट रूप से कहता है।

— ब्रेंडन लांग

Answer 10

मैंने हमेशा C ++ हैडरफाइल्स में टिप्पणियां लिखना सीखा (क्योंकि यह हमेशा स्पष्ट नहीं होता है कि कोई फ़ंक्शन क्या करता है, हालांकि नाम एक अच्छा संकेत देता है) खासकर यदि आप अन्य डेवलपर्स पर एपीआई पास करते हैं या ऑक्सीजन जैसे ऑटोडोक के लिए एक उपकरण का उपयोग करते हैं।

तो मेरे लिए एक सामान्य टिप्पणी कुछ इस तरह दिखती है

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

केवल उसी समय जब मैंने टिप्पणियों का इस्तेमाल किया, वह सामान है जिसे समझ पाना कठिन है और कभी-कभी प्रोग्रामर के लिए भी, जैसे "यह नहीं करना चाहिए! क्योंकि ..." या "PROGRAMM WILL CRASH IF LINE IS DELETED ..."

Workarounds, हैक्स और अजीब व्यवहार मेरी आँखों में WHY मानदंडों के लिए योग्य है ...

एक बहुत अच्छा और यहां तक ​​कि प्रफुल्लित करने वाला उदाहरण है रिचर्ड नाम के किसी व्यक्ति द्वारा लिखे गए कुछ गड़बड़ कोड के लिए यह "वर्कअराउंड" है, किसी और ने इसे लपेटा और बताया कि टिप्पणियों में क्यों ... https://stackoverflow.com/a/184673/979785

दुर्भाग्य से कई बार ऐसा होता है, जहाँ आपको बैल को लपेटने के लिए मजबूर किया जाता है **** क्योंकि आप मूल को छू नहीं सकते हैं, या तो क्योंकि "यह हमेशा से इस तरह से रहा है" या आपके पास पहुंच नहीं है या ... ठीक है, आप वास्तव में ओवरहेड के लिए योग्य नहीं होने के लिए मूल को ठीक करने का समय नहीं है।

Comments

सिवाय इसके कि सवाल टिप्पणियों के बारे में है , दस्तावेज के बारे में नहीं । वे वास्तव में अलग-अलग चीजें हैं ( documentationटैग अफसोसजनक है लेकिन फिर भी सवाल पर लागू नहीं होता है)।

— थॉमस

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

— AnyOneElse

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

— ब्रायन ओकले

हालांकि मैंने कहा कि मेरे कोड में बहुत कम WHYs हैं, और मैंने दो उदाहरणों का नाम दिया: EDITED ... यहाँ एक लिंक है, जो निश्चित रूप से WHY के लिए योग्य है

— AnyOneElse

@AnyOneElse मैंने डाउनवोट नहीं किया। मेरे आने से पहले यह वहां था।

— थॉमस

Answer 11

कोड निष्पादन योजना को निर्दिष्ट करने वाला है। इस तरह प्रोग्राम फॉलोअर (या कंपाइलर) यह पता लगा सकता है कि क्या करना है, और यह कैसे करना है। प्रोग्राम अनुयायी का अनुसरण करने वाले चरणों में क्या टूट गया है। आदिम कदम कैसे हैं।

कोडर का इरादा एक और मामला है। सरल, स्पष्ट, स्पष्ट कोड में मंशा स्पष्ट है। किसी भी कारण से प्रवीण मानव पाठक कोड के ब्लॉक के इरादे से पहुंच जाएगा, बस कोड को पढ़कर। अधिकांश कोड को इस तरह पढ़ना चाहिए।

कभी-कभी, इरादे और योजना के बीच संबंध अस्पष्ट होता है। कोड से पता चलता है कि क्या और कैसे, लेकिन क्यों नहीं। जब इरादे प्रकट करने वाली टिप्पणियाँ सार्थक होती हैं। प्रोग्रामर का इरादा क्यों है।

Comments

उदाहरण के लिए सवाल एक दो बार पूछता है। क्या आप इसे अधिक उपयोगी बनाने के लिए अपने उत्तर में एक उदाहरण जोड़ सकते हैं?

— ब्रायन ओकले

Answer 12

इस मुद्दे के होने के बाद अभी एक जटिल और कुछ हद तक जटिल डेटा मॉडल के खिलाफ संग्रहीत प्रक्रियाओं और विचारों के माध्यम से वैडिंग है।

हमारे पास (कई) ऐसे मामले हैं, जैसे "केस जब x.account null नहीं है और x.address इन (फ़ेडेक्स से चयन पता) है तो x.account और y.account अंत" पूरे और उत्पादकता की उम्मीद है, हालांकि समय नहीं है सभी सभी स्रोत कोड को पढ़ने के लिए। और यह उदाहरण दयालु प्रकार की तरह समझ में आता है, लेकिन यह अभी भी असंवेदनशील है।

टिप्पणियों में बताया गया है कि क्यों फ़ेडेक्स में है तो x और यदि नहीं तो y - पूरे सिस्टम पर प्रकाश डालता है और जब हम उनमें से पर्याप्त पढ़ते हैं तो हम इसे प्राप्त करना शुरू करते हैं। और यह सरलीकृत हो गया है और सैकड़ों या हजारों समान कथन हैं। मेरा दिल इस बात की ओर गर्मजोशी से है कि जो भी 2007 से दयालु देव था, उन लोगों में क्यों डाला गया था।

तो हाँ, जटिल जटिल डेटा मॉडल और बालों वाली veiws और कई वैध तरीके से नामित रास्तों के साथ संग्रहीत प्रक्रिया, कृपया जीडी के प्यार के लिए हमें बताएं क्यों।

Answer 13

मैंने अभी यह टिप्पणी लिखी है; यह समझाने का एक ठोस उदाहरण है कि कोड की एक पंक्ति क्यों है, यह क्या है, और विशेष रूप से मैंने इसे क्यों बदल दिया।

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

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

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