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

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

• एस। मैककॉनेल, "परफेक्ट कोड। मास्टर वर्ग
• आर। मार्टिन, "क्लीन कोड। निर्माण, विश्लेषण और रीफैक्टरिंग ”
• डी। बोसवेल, टी। फाउचर, "पठनीय संहिता, या एक कला के रूप में प्रोग्रामिंग"

तो क्या मुझे टिप्पणियों में इतना गुस्सा आता है? मैं कुछ बुनियादी बिंदु दूंगा:

• टिप्पणियाँ तत्काल कोड को अव्यवस्थित करती हैं, पठनीयता बिगाड़ती हैं
• टिप्पणियां लिखने और समर्थन करने के लिए समय लेती हैं
• टिप्पणियाँ झूठ (कुटिल से लिखित, अप्रचलित के साथ समाप्त)

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

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

जब आप टिप्पणियों के बिना कर सकते हैं

टिप्पणियाँ जो कोड दोहराती हैं

आइए कोड पर एक नज़र डालें:

//        
public int CalcSumOfElement(int[] elements) //      
{
  int result = 0; //     
  int n = elements.Length; //   , ..  
  for (int i = 0; i < n; i++) //     
    result += elements[i]; //     
  return result; //  
}

, , , , , . . — . . : . , — .

,

, :

public class Item
{
  private int value; //   ,    

  //  
  public Item(int twoValue)
  {
    value = twoValue >> 1; //       
    //       
  }
}

, . , , . , .

,

HashSet<int> set; //   ,   -
//     
//     ,        
//   -    : http://ru.wikipedia.org/wiki/%D0%A5%D0%B5%D1%88-%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D0%B0

- , / / . . .

,

//    
// public void DoIt()

, ///. , . - , , . ! - - ?

,

: «, 300 , . . 10- , ». , , , - . 300- . — .

,

public int GetSeconds(int hours)
{
  return hours * 3600; // 3600 -   ,  
}

, , — , , . , . , :

private const int SecondsInHour = 3600;
public int GetSeconds(int hours)
{
  return hours * SecondsInHour;
}

,

« » , .

MOV AX, 723h ; R. I. P. L. V. . 

, : «Rest in peace, Ludwig van Beethoven», .. 723 — .
, , . ( ), - ( « , , »). , . , - .

,

, , . .

public void Main()
{
  // ,    .
  //      .
  //      Run.
  //   , Run  «».
  //      ,   .
  //    ,   .
  //     ,         Main.
  //      ,    Main.
}

,

, , . , , .

// Sum(1, 2) == 3
// Sum(2, 1) == 3
// Sum(2, 2) == 4
public int Sum(int a, int b)

— . , Unit-. . Unit- — . - , Unit-?

,

, , :

// 11.06.13:    .    - -,    .
// 12.06.13: ,   —   .   .

: — . . , . - , .

,

. , , - . :

// int number = GetNumber()
// int number = 4;
// int number = 5;
int number = 4;
// double number = 4.5;
// decimal number = 4.5;
// string number = " ";

? : , , . , — . , . , . , , : « , , , , ».

,

bool flagA = true;
bool flagB = false;
bool flagC = true;
if (Condition(flagA, flagB, flagC))
  Foo();
// else   true,  

. true? true else- , true. , ? ?
, . , . ! , , .

,

. , . . , , , - ASCII-, , . , .
, . , (, ).

,

//   
public int Sum(int a, int b)

. ? , - , , . : , . , . , , , .

,

, , , . - . , , .

,

, , . , . , - , . , , «» . , , . , .

, TODO

- . , IssueTacker, . , Issue, , , . , IDE TODO- , . , . TODO- , .

,

- , , . , , . , , - , . , .. , . , - , — , .

,

( ). , , . API, private- . , . , , .

,

- , .. , — , .

: , , — , . , , — , , . , , , . , — , - .

Update:
, , , , . , ( , , ..). , , (, ). , 100 , , . , . , : — , , . — .