Category: A Hypocrites Guide To Comments


In University Wednesday afternoons are dedicated to sports, as this is when most BUSA sports teams play. However, if they’re not interested in sports the students get the afternoon off, and this leaves a gap in the timetable that we couldn’t help but fill.

“Rather Useful Seminars” are dedicated to things that we think the students might find rather useful, but that are not appropriate to put into the main curriculum. I did a couple recently, and sandwiched between them, like the glorious filling between two past their best crusts of bread was a great talk from games industry veteran David Clark. Now I’m cramming all three into one blog post!

My first crust was immediately after the three thing game, and was about getting your game into the market place. It was more about the “Why” than the “How”, and the aim was to convince students that even though it’s unlikely that they will make a lot of money, getting a game (or games) out there is a great way to bolster your portfolio, and a way to get networking. Maybe “publishing games for employability” would have been a better title. Still, I cited some success stories from the games industry, and looked at what that success took, and I talked about the non-monetary goodness you get from publishing.

The following week Dave Clark did his thing again. He gave a great deal of insight into the business side of the industry. What publishers are for, how their role has changed etc. It was a fascinating talk and I know I won’t be able to do it justice here. I would like to extend my thanks for the talk though. A highlight was that Dave also mentioned the importance of networking. It’s something that typical computer scientists don’t enjoy very much, but it opens doors to where you want to go – so it’s got to be done. Thanks again Dave!

Last week I did a seminar on how to comment code. I talked about how commenting is hard, because comments aren’t compiled, they aren’t tested, and there is little feedback as to what makes a good comment. Then I gave some examples of code that I had commented and asked the students which pieces of code were commented well, and which were commented badly. We face a bit of a problem when we’re teaching students code, because often we use comments to tell the students (as people who don’t understand code) exactly what the code does. In the industry (where everyone can read code) this would likely be regarded as over-commenting and cluttering up the code base. A better approach is to consider Why you are doing something a particular way, instead of How.

I also covered using comments to document your code, both through intellisense and using tools like Doxygen, and the worst comment of all – the comment that is incorrect!

The students responded really well to the examples, and seemed to understand what I was saying. Whether they can put it into practice is another matter though. I knew exactly what I was saying, yet I still find commenting my own code well and extremely difficult thing to do!

Advertisements

A while ago I read an excellent book called The Pragmatic Programmer. One of the main themes throughout the book was the DRY principle. DRY stands for Don’t Repeat Yourself. I’ll blog about that another time, as talking about it now would be a violation of the DRY principle later. Anway, the authors of the pragmatic programmer suggest that in order to avoid repetition in different forms where possible code should document itself.

Visual Studio offers a tool to help you do this. You can decorate your code with special comments by typing in three forward slashes. One of those tools is the xml comments feature that helps you comment functions in a useful way.

 /// <summary>
 /// A summary of what this method does.
 /// </summary>
 /// <param name="pFantasticString">The significance of the pName parameter that is passed in.</param>
 /// <returns>Information about what this method returns</returns>
 static bool AwesomeMethod(string pFantasticString)
 {
    return true;
 }

This is really handy for two reasons. The first is because it gives you a helpful structure, and a reminder about what sort of information you might want to put in your comments (However sometimes good naming of variables make the comments a little redundant). The really nice thing about documenting your code in this way is that visual studio can use this to populate intellisense, so people using this method don’t even have to find the definition to read these comments. They just pop up as and when they might be required.

Two examples of intellisense using my comment to deliver information when it might be needed

As I said, good method and function names can sometimes render such comments redundant, but sometimes they are invaluable.

Intellisense being really useful

Take this example using the .net Random class. This comment reassures me that if I ask for a random number and pass in 0 and 5, then there is a chance I will get 0, rather than the lowest value possible being 1.

Additionally, by checking a box in a project’s build menu you can get visual studio to create an xml file of your project. This could be used to create documentation for the internet automatically, using tools such as Sandcastle.

To do lists are wonderful things. When you have a lot of things to do they help you to organise and prioritise all those things, they give you satisfaction when you cross something off your list, and they give you feedback on how you’re doing and whether you need to put some things on the back burner for a while.

Visual studio offers a built in task list to which you can add user tasks, assign priorities and tick off completed tasks.

User Task List – I wish my real to do list was this empty ๐Ÿ˜ฆ

There’s more though, the Task List will also scan your code for token comments – which are special comments containing specific strings.


// TODO: Refactor constructors to use constructor chaining

#region Constructors

#endregion

// HACK this works but it is bad practice to make this method public
 public int GetNextAccountNumber()
 {
return m_NextAccountNumber;
 }

By looking at the comments section you can see a TODO comment and a HACK comment that have been picked up automatically by the task list which read the comments in the code. Once the task is done the comment is deleted.

These tasks have been generated by reading comments in the code

You can even specify your own tokens. They say that you shouldn’t worry about making code more efficient until efficiency actually becomes a problem.

Adding a new INEFFICIENT token – it’s low priority though because efficiency isn’t an issue yet

You can add your own tokens by selecting Tools ->Options -> Environment -> Task List. Here I’ve created an INEFFICIENT token, so that if I write code that I know could be more efficient I can give it the INEFFICIENT token, and if I have to look for ways to speed up code later I can look for all the pieces of code that have been given this token.

Now if I ever want to speed up my code I’ll know just where to look!