अगर-और-क्लॉस टिप्पणी करने का एक अच्छा तरीका क्या है? [बन्द है]

Question

जब भी मैं किसी भी भाषा में एक विशिष्ट if-else-निर्माण लिख रहा हूं तो मुझे आश्चर्य होता है कि टिप्पणियों को जोड़ने के लिए सबसे अच्छा तरीका (पठनीयता और अवलोकन के रूप में) क्या होगा। खासतौर पर तब जब कमेंट क्लॉज करते हैं तो हमेशा मेरे लिए आउट-ऑफ-प्लेस महसूस होता है। कहें कि हमारे पास इस तरह का एक निर्माण है (उदाहरण PHP में लिखे गए हैं):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

मैं इसे इस तरह से टिप्पणी कर सकता हूं:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

या

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

या

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

यह टिप्पणी करने के लिए आपके सर्वोत्तम अभ्यास के उदाहरण क्या हैं?

Comments

else { // for future reader: sorry, at the moment of writing this I did not have time and skills to come up with a better way to express my logic

— gnat

बड़ा बेहतर / बेहतर / अलग क्यों है? देखिए, मुझे नहीं पता

— जेएफओ

क्या यह सवाल या बहस का विषय है? यहां तक ​​कि अगर सवाल अच्छी तरह से मतलब है, वे युद्ध शुरू करने वाले हैं।

— स्वतंत्र

मुझे यह दिलचस्प लगता है कि इतने सारे लोगों ने महसूस किया है कि यह सवाल उनके जवाब देने के लायक था, लेकिन उत्थान के लायक नहीं था। जब मैं जवाबों में दिलचस्पी लेता हूं (मेरा एकमात्र एकमात्र है), सवाल एक बाइक-चालन समस्या का एक सर्वोत्कृष्ट उदाहरण प्रतीत होता है।

— canisrufus

@canisrufus यह आपको केवल इस तरह दिखता है क्योंकि नीचे के वोट ऊपर के वोटों को भर देते हैं। इस समय, नेट +2 के लिए 6 अप और 4 डाउन वोट हैं।

— कालेब

Answer 1

मैं या तो पसंद करते हैं:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

या:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

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

मैं "टिप्पणियों को कभी नहीं लिखता" दर्शन की सदस्यता नहीं लेता, लेकिन मैं टिप्पणियों से बचने में विश्वास करता हूं जो कहते हैं कि कोड को क्या कहना चाहिए। यदि आप एक टिप्पणी लिखते हैं जैसे "चेक करें कि किस तरह का जादू होना चाहिए" जब कोड कह सकता है if ($magic == big) {..., तो पाठक आपकी टिप्पणियों को बहुत तेज़ी से पढ़ना बंद कर देंगे। कम, अधिक सार्थक टिप्पणियों का उपयोग करने से आपकी प्रत्येक टिप्पणी को अधिक मूल्य मिलता है, और पाठक उन पर ध्यान देने की अधिक संभावना रखते हैं जो आप लिखते हैं।

अपने चर और कार्यों के लिए सार्थक नाम चुनना महत्वपूर्ण है। एक अच्छी तरह से चुना गया नाम आपके कोड में व्याख्यात्मक टिप्पणियों की आवश्यकता को समाप्त कर सकता है। आपके उदाहरण में, $magicया शायद आपके उदाहरण के अनुसार $kindOfMagic, एक बेहतर नाम की तरह लगता है $big, यह "जादू की तरह" है जिसका परीक्षण किया जा रहा है, न कि किसी चीज़ की "गरिमा"।

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

Comments

+1 टिप्पणी से अधिक नहीं है, स्पष्ट कोड के लिए कोई टिप्पणी की आवश्यकता नहीं है

— शाफ़्ट फ्रीक

@ratchetfreak लगता है जैसे हम ज्यादातर समझौते में हैं, लेकिन कोड को स्पष्ट करने के लिए टिप्पणियां अक्सर आवश्यक होती हैं। ऐतिहासिक संदर्भ प्रदान करना, आश्चर्यजनक व्यवहार के लिए समझाना या अस्पष्टता को हल करना टिप्पणियों के साथ सबसे अच्छा किया जाता है।

— कालेब

अच्छा बिंदु, कालेब। यह सच है कि कोड को किसी तरह का ऑटो-कमेंट करना चाहिए जब तक यह संभव है।

— acme

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

— ब्रूनो ब्रांट

परेशानी यह है कि कोड पढ़ना मुश्किल है और टिप्पणी नहीं लिखना आसान है। कोड को पढ़ना मुश्किल लिखना आसान है, लेकिन यह अच्छी तरह से टिप्पणी करना है क्योंकि यह लगातार कोड लिखना इतना अच्छा है कि इसे टिप्पणियों की आवश्यकता नहीं है।

— 19

Answer 2

व्याख्यात्मक चर नामों का प्रयास करें

टिप्पणियाँ महान हो सकती हैं, लेकिन जब संभव हो, कोड को स्व-दस्तावेजीकरण करें। ऐसा करने का एक तरीका व्याख्यात्मक चर नामों के साथ है। उदाहरण के लिए, इसके बजाय:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

मैं एक नामित चर पसंद करूंगा:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Comments

मैं एक कदम आगे जाता हूं और उपयोग करता हूं is_potential_elvis_impersonator:। (ब्यूसियन वैरिएबल के लिए इज़ / है / आदि उपसर्ग है।)

— जेक बर्गर

@jberger - मुझे यह पसंद है। तदनुसार उत्तर दें।

— नाथन लांग

Answer 3

बस कुछ टिप्पणियों को पूरा करने के लिए:

टिप्पणियों का उचित उपयोग कोड में खुद को व्यक्त करने में हमारी विफलता के लिए क्षतिपूर्ति करना है। ध्यान दें कि मैंने विफलता शब्द का उपयोग किया है। मैं दिल से ऐसा चाहता था। टिप्पणियाँ हमेशा विफल होती हैं। हमें उनके पास होना चाहिए क्योंकि हम हमेशा उनके बिना खुद को व्यक्त करने का पता नहीं लगा सकते हैं, लेकिन उनका उपयोग उत्सव का कारण नहीं है। ( रॉबर्ट सी। मार्टिन द्वारा स्वच्छ संहिता )

BTW: मैं इस पुस्तक की सिफारिश करता हूं।

Answer 4

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

आप कभी-कभी महसूस कर सकते हैं कि elseशाखा की शुरुआत में एक पैराफ्रेसेज की आवश्यकता होती है , लेकिन यह अक्सर संकेत है कि आपकी thenशाखा बहुत बड़ी है।

Answer 5

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

इसके साथ अपने स्निपेट की तुलना करें:

if ($x) {
    func1();
} else {
    func2();
}

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

सामान्य तौर पर, मैं उन तार्किक ब्लॉकों के लिए टिप्पणियां लिखना पसंद करता हूं जो उन चीजों का वर्णन करते हैं जो कोड स्वयं नहीं कर सकते। एक-लाइनर हर ~ 10-20 पंक्तियों का वर्णन करता है कि निम्नलिखित मुट्ठी भर लाइनें क्या अमूर्तता के एक उच्च स्तर (जैसे // Make the right amount of magic happenआपके उदाहरण के लिए) को पूरा करती हैं, जो आपको उन्मुख रखने में मदद करती हैं और आप क्या कर रहे हैं और कब नया समीक्षक अंतर्दृष्टि देते हैं ।

कोड लिखने शुरू करने से पहले मैं वास्तव में अक्सर इन वन-लाइनर्स को लिखता हूं, ताकि मैं उस प्रवाह का ट्रैक न खोऊं जो कि खंड को माना जाता है।

अंत में, यदि आप वास्तव में पसंद करते हैं (या एक जनादेश है जिसकी आवश्यकता है) कोड की पठनीयता की परवाह किए बिना यदि एक ब्लॉक में खंड टिप्पणी करता है, तो मैं सुझाव देता हूं:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

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

Answer 6

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

मैं अपने ब्रैकेट्स को लाइन में रखता हूं और ब्रैकेट के ठीक बाद लगाता हूं।

[Condition] -> [pseudo-code]

दूसरी ओर, इसका तकनीकी रूप से मतलब है कि अन्य सभी स्थितियां विफल रहीं, इसलिए मैं आमतौर पर कोष्ठक का उपयोग करता हूं।

([Condition]) -> [pseudo-code]

नोट: यह C # के लिए है।

Answer 7

मैं ब्लॉक के अंदर टिप्पणियों का उपयोग करने की कोशिश करता हूं और कहता हूं कि वह ब्लॉक (आपका पहला नमूना) क्या करता है।

जहां इस थोड़े 'का उपयोग करते समय टूट जाता है elseif। मैं बेसिक का उपयोग करता हूं, इसलिए कोई स्पष्ट अंत ब्लॉक नहीं है और अक्सर यह टिप्पणी करना पड़ता है कि क्या स्थिति की जांच हो रही है जो ऊपर की लाइन पर जाती है (निश्चित रूप से एक लाइन ब्रेक के साथ) यदि यह बहुत लंबा है।

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

Comments

हां, यह वास्तव में बेहतर काम कर रहा है जब आप कोष्ठक के बिना एक भाषा का उपयोग कर रहे हैं।

— acme

Answer 8

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

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

Answer 9

C ++ या C # में मैं आमतौर पर सरल मामलों (जब इसका स्पष्ट क्या हो रहा है) पर टिप्पणी नहीं करेगा, और अंतिम टिप्पणी करने के लिए इस प्रकार की शैली का उपयोग करें ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}

Comments

या बेहतर, "pattern.doSomething ()" और OO को अपना काम करने दें।

— पॉल टॉम्बलिन