अगर किसी और की संरचना पर टिप्पणी कैसे की जानी चाहिए?

Question

मान लें कि आपके पास है:

if(condition) { 
    i = 1; 
} else { 
    i = 2; 
} 

और आपको if और else ब्लॉक समझाते हुए टिप्पणियां देने की आवश्यकता है। ऐसा करने का सबसे पठनीय तरीका क्या है ताकि कोई उन्हें पहली नज़र में आसानी से उठा सके?

मैं आमतौर पर ऐसा करता हूं:

//check for condition 
if(condition) { 
    i = 1; 
} else { 
    //condition isn't met 
    i = 2; 
} 

जो मुझे पर्याप्त स्तर पर नहीं मिलता है क्योंकि टिप्पणियां विभिन्न स्तरों पर स्थित होती हैं, इसलिए त्वरित नज़र में आप बस if टिप्पणी उठाएंगे और else टिप्पणी इस तरह दिखेगी कुछ आंतरिक संरचना से संबंधित है।

उन्हें इस तरह रखकर:

if(condition) { 
    //check for condition 
    i = 1; 
} else { 
    //condition isn't met 
    i = 2; 
} 

मेरे लिए अच्छा नहीं लग रहा है क्योंकि ऐसा लगता है कि पूरी संरचना पर टिप्पणी नहीं की गई है (स्थिति बड़ी हो सकती है और कई लाइनें ले सकती है)।

कुछ ऐसा है:

//check for condition 
if(condition) { 
    i = 1; 
//condition isn't met 
} else { 
    i = 2; 
} 

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

आप ऐसे ब्लॉक कैसे टिप्पणी करते हैं?

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

Answer 1

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

Answer 2

आपको केवल तभी टिप्पणी करनी चाहिए यदि कोड स्वयं व्याख्यात्मक नहीं है। तो अगर आत्म व्याख्यात्मक बनाओ। इस तरह शायद

bool fooIsNotReallyGood = ....; 

if(fooIsNotReallyGood) { 
... 
} else { 
... 
} 

Answer 3

//condition isn't met एक बेकार टिप्पणी प्रतीत होता है। लेकिन इस मामले में जहां इस तरह के एक टिप्पणी की आवश्यकता है में मैं इस तरह (सी #) यह कार्य करें:

//check for condition 
if(condition) 
{ 
    i = 1; 
} 
//some other condition 
else 
{ 
    i = 2; 
} 

हालांकि, ब्लॉक है अगर सिर्फ अगर-बाकी, की तुलना में मैं पहले अगर दोनों टिप्पणियों विलय होगा।

जावास्क्रिप्ट के लिए मैं पसंद करते हैं

//check for condition 
if(condition) { 
    i = 1; 
} else { //some other condition 
    i = 2; 
} 

पी.एस. लगता है के रूप में कई राय के रूप में वहाँ लोग :)

Answer 4

आप तरीकों की if-else कोड निकालने और उन्हें ठीक से नाम हो सकते हैं:

function main() { 
    checkForCondition(condition); 
    conditionIsNotMet(condition); 
} 

function checkForCondition(boolean condition) { 
    if (condition) { 
    i = 1; 
    } 
} 

function conditionIsNotMet(boolean condition) { 
    if (!condition) { 
    i = 2; 
    } 
} 

इस तरह के एक तुच्छ मामला यह एक overkill की तरह लगता है में, लेकिन अधिक होने की कल्पना if-else शाखा प्रति एक पंक्ति से अधिक।

Answer 5

एक अन्य विकल्प है:

if(condition) { //check for condition 
    i = 1; 
} else { //condition isn't met 
    i = 2; 
} 

Answer 6

चर महत्वपूर्ण हैं, नहीं की स्थिति के लिए खुद को।

if condition: # <condition dependent variable> was <predicated> 
    dosomething() 
elif othercondition: # <othercondition dependent variable> <predicated> 
    dootherthing() 
else: # <all variables> <not predicated> 
    doelsething() 

Answer 7

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

आत्म टिप्पणी स्थितियों के लिए

if (condition) //if above the bar 
{ 
    i = 0; 
    k = 1; 
} 
else    //else if below 
{ 
    i = 1; 
    k = 2; 
} 

Answer 8

जाओ करने के लिए टैब किए गए, तो कोई अतिरिक्त टिप्पणी आवश्यक नहीं हैं। मान लें कि शर्त यह है कि अधिकतम ऋण मूल्य तक पहुंच गया है। यह हमें देता है:

if (maximumLoanToValueIsReached) 
{ 
    i=1; 
} 
else 
{ 
    i=2; 
} 

जब मैं = 2 कि मूल्य को अधिकतम ऋण के रूप में है कि आत्म explanitory है पहुँच नहीं किया गया है निर्दिष्ट करने के लिए कोई ज़रूरत नहीं। एक तरफ के रूप में, मैं कुछ और अर्थपूर्ण के लिए i का नाम भी बदलूंगा।

Answer 9

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

if (condition) { 
// User is taking a course at college x: 
    i = 1; 
} else { 
// User is not taking any course at college x: 
    i = 2; 
} 

Answer 10

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

// If the condition for a local tree imbalance is met, 
    // juggle the immediate nodes to re-establish the balance. 
    // Otherwise, execute a global balancing pass. 
    if (somewhat muddled condition) 
    { 
    ...code... 
    } 
    else // Tree is in local balance 
    { 
    ... more code... 

    } // if/else (tree locally imbalanced) 

अंतिम '}' पर टिप्पणी मुख्य रूप से मौजूद है हालत अधिक विज़ुअल भार के अंत देने के लिए, बनाने के लिए:

तरह से मैं नहीं तुरंत आत्म व्याख्यात्मक स्थितियों के लिए टिप्पणियों को संभालने के इस तरह है स्रोत के माध्यम से पढ़ने के लिए आसान है।

Answer 11

कोड पहले से ही आत्म दस्तावेज़ीकृत नहीं है, तो मैं इसे संरचना देंगी:

if (someCondition) { 
    // If some condition, then do stuff 1. 
    doStuff1(); 
} 
else { 
    // Else do stuff 2. 
    doStuff2(); 
} 

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

if (x == null || x.startsWith("foo") || x.endsWith("bar") || x.equals("baz")) { 
    doStuff1(); 
} 
else { 
    doStuff2(); 
} 

तो मैं के रूप में यह refactor करने के लिए विचार किया जाएगा:

boolean someCondition = (x == null || x.startsWith("foo") || x.endsWith("baz") || x.equals("waa"); 

if (someCondition) { 
    doStuff1(); 
} else { 
    doStuff2(); 
} 

जिसमें चर नाम someConditionवास्तव में में पूरे हालत को सारांशित छिलका। जैसे usernameIsValid, userIsAllowedToLogin या तो।

Answer 12

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

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

/* 
** Comment explaining what the condition 
** is trying to determine 
*/ 
if (condition) 
{ 
    /* 
    ** Comment explaining the implications 
    ** of the condition being met 
    */ 
    do_something(); 
} 
else 
{ 
    /* 
    ** Comment explaining the implications 
    ** of the condition not being met 
    */ 
    do_something_else(); 
} 

किसी भी मामले में, टिप्पणियों को कोड को दोहराना नहीं चाहिए।