Don’t be a parrot programmer

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.

Marking 08120

I spent the Friday before the bank holiday, and will spend tomorrow marking programming 2 coursework with Rob, Martin, David and Mile. Although I complain I do like to see what the first years have achieved and I am always pleasantly surprised by what I see.

This year the students had a choice between making a bank application, or an XNA game called sweepy cleaner. Some students went as far as to make versions for the Windows Phone 7 or the PS Vita!

Sweepy Cleaner on Windows Phone – excellent!

I saw some great banks and some great games, and a good deal of great students who for the most part seemed generally interested in any feedback I was able to offer. If the first day is anything to go by we should be putting out some really good graduates in a couple of years time!