If the code is self-documenting, then why do we need to add comments at all? This is certainly the feeling of some programmers. When the comments aren't doing more than simply repeating the code, or when comments are out of date and difficult to update, then it is easy to understand why they feel that way. However, this is the opposite of what good comments should be.

Good comments should explain things that the code cannot. For example, copyright information, or author and contact information are things that can't be represented in code, but may be of use to the reader. Additionally, good comments do not simply repeat the code. The comment below is completely worthless. It adds nothing to the code:

//Assign START_VALUE to x 
int x = START_VALUE; 

Instead, good comments should explain the intent and purpose of the code. Even if you understand what a block of code is supposed to do, you can't know what the author was thinking when they wrote it. Knowing what the author was trying to accomplish can save you a lot of time when debugging someone else's code:

/****************************************************************/ 
/*! 
Given an array of "arraySize" mark all indices that are prime as true. 
 
param [out] primes  
The array to modify and Output. 
 
param [in] arraySize  
  The number of elements in the array 
 

eturn  
  None. Indices that are prime will be marked as true 
 
*/ 
/****************************************************************/ 
void CalculateSievePrimes(bool primes[], int arraySize) 
{  
  /*Ensure array is properly initialized */    
  for(int i = 0; i <size; ++i) 
    primes[i] = true; 
    
  /*Zero and One are never prime*/  
  primes[0] = primes[1] = false; 
   
/*Check values up to the square root of the max value*/ 
  int upperBound = static_cast<int>(std::sqrt(arraySize)); 
 
  /*Check each value, if valid, mark all multiples as false*/ 
  for(int candidate = 2; candidate <= upperBound; ++candidate) 
  { 
    if(primes[candidate] == false) 
      continue; 
       
    int multiple = candidate * 2; 
    for(; multiple < arraySize; multiple += candidate) 
      primes[multiple] = false; 
  } 
} 

The comments above explain what the author was thinking while writing the code. They do not just repeat what the code is doing. Notice that some comments explain a single line, while other comments summarize entire code blocks. There aren't any hard rules about how many comments should be in your code. A rough suggestion is that every code block should have a comment explaining its purpose, with additional comments for more complex lines.

The comment blocks such as the one at the top of the method are the least likely to be used but they can serve an important purpose as well. Just as the section headers of this book help when you are scanning for something specific, function headers can help you when scanning a source code file looking for a specific function.

Functions headers can be very helpful because they summarize everything about the function without the need to look at the code. Anyone can easily understand the purpose of the parameters, return values, and even any exceptions that may be thrown. The best part is, by using a tool such as Doxygen, the header blocks can be extracted to make external documentation.

Of course, these are the most difficult to write and maintain. It is comment blocks like these that often become out of date or are flat out wrong. It is up to you and your team if you want to use them. It takes discipline to keep up with them, but they can be worth it if you happen to be working on another programmer's code after they have left the team.