When students are learning to program they know that they should comment their code, but knowing what code to comment is an art, as is knowing what code not to comment. Sometimes, especially if comments are mentioned in the marking scheme, students will make an extra effort to add comments. Often that results in what I call parrot comments.

Take a look at this code that gets a random integer:


Random randomNumberGenerator = new Random(); // Random Number Generator

int getRandomInteger(int pMinimum, int pMaximum)
{
    return randomNumberGenerator(pMinimum, pMaximum); // returns random integer between pMinimum and pMaximum
}

This is what I call parrot commenting, and I think it’s symptomatic of someone who knows they should comment, but doesn’t know what to comment.

Comments should always add something more to the code; otherwise they aren’t comments, they’re just clutter. This is made worse in the code above, because the comment is worse than clutter. It is actually wrong!

Random randomNumberGenerator = new Random();

int getRandomInteger(int pMinimum, int pMaximum)
{
    // returns random integer greater than or equal to pMinimum but less than pMaximum
    return randomNumberGenerator(pMinimum, pMaximum); 
}

This comment is correct, and it adds something to the code that we didn’t know before – so it passes the clutter test. I think the key to comments is to describe what you are doing and why as you write the code. Otherwise you come back, read the code and describe what you have read. Well any programmer could do that.