A really good comment is one

without which you managed to do.

Uncle Bob



Recently, I have become very tired of lively debates on whether to comment on the code. As a rule, on one side of the barricades are arrogant juniors who have an indisputable position of the form “But how can one not comment on it, because without comment it will be incomprehensible!” . On the other - seniors, wise by experience. They understand that if it is possible to do without comments, then "It would be better, damn it, so be it!" . Probably, for many, the thirst for comment comes from the student's bench, when fellow teachers made us comment on each line, “so that the student could understand it better” . In a real project, there should be no heaps of comments, which are the only thing that makes the code dirty. However, I do not agitate not to write comments at all, but if you managed to write such code that does not require explanations, then regard it as your little victory. At once I would like to refer to several very clever books, on the basis of which my position was formed. I love and respect the authors of these works, fully sharing their opinions.

• S. McConnell, “Perfect Code. Master Class"
• R. Martin, “Clean Code. Creation, analysis and refactoring »
• D. Boswell, T. Foucher, “Readable Code, or Programming as an Art”

So, what annoys me so much in the comments? I will cite a few key points:

• Comments litter the immediate code, impairing its readability.
• Comments take time to write and support
• Comments are lying (starting from crookedly written, ending obsolete)

In principle, I agree that in some cases, comments are still needed. But your code will be the more beautiful, the less there will be such cases. In addition, writing a good comment is also an art. Alas, not so many programmers have it, most write comments anyhow. The benefits of this are often questionable. And how to spend time and energy on writing a good literate comment, is it not better to spend money on rewriting the code so that it no longer requires a comment?



Let's discuss some typical scenarios in which you can say something definite about the need for a comment. I cite code examples in C #, but for this topic it doesn't matter.

')

When you can do without comments

Comments that repeat the code

Let's take a look at the code:

//        
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 , , . , . , : — , , . — .