Teaching Students to Comment Part 2

My first blog on teaching comments received some interesting and valuable comments from professionals and I really appreciate them. While I spent a large part of my career as a software developer it has been a while since I’ve worked on a big project and so the comments have provided some useful reminders.

Shaun Bedingfield pointed out the importance of writing readable code. And he’s right of course. Readable, self-documenting codes makes for very maintainable code. I think students tend not to understand the importance of choosing variables wisely. Comments explain things strategy. Shaun’s suggestion of writing pseudo code first and keeping that pseudo code as part of the basic commenting structure is a good one. And really it is a variation of what I suggested in the first post. The principle hope to promote is that of thinking out the algorithm before writing code.

I believe that writing well commented stub code (code that compiles but doesn’t really do anything) can help build a structure that can be filled out as development progresses. This requires that the function/method/class has a good name, properly named parameters and some good comments that explain what is to come.

Shaun also points out that the programs that most need comments are not likely to be found in the typical student project. That is because it is pretty easy to keep a small project in ones head with a high level of understanding. If the program is self documenting with good naming convention comments often seem superfluous. Students are going to argue that. I think there are two good answers for that though. One, the simple one, is just that commenting from the start builds good habits. Building good habits is what practice is all about. The other answer is to expose students to actual large projects.

The case study that is part of the Advanced Placement exam is one such project. It is large enough that having comments to explain how classes and their methods work makes a lot of sense. But there is a lot of sample code out there that can be used for this purpose. Seeing is generally believing. Traditionally teachers have not exposed their students to reading a lot of code in the early classes. A lot of people have been suggesting that this change and I agree. I would like to see more students read a lot more code. I’ll have more to say about that as time goes on.

Marcelo, a developer in test at Microsoft, linked back to my blog and had a lot of useful things to say in his own blog. He reiterates the value of proper naming and adds some talk about refactoring. Refactoring is a whole other topic but one with I think too many students and their teachers (especially at the secondary level) are unfamiliar with. Refactoring tools in Visual Studio .NET 2005 make this a lot easier to do and to teach.

Marcelo also points out the difference between comments in a function header and a function body. Conveniently that is what I had in mind to talk about for this part 2 from the start. No, really!

The C# programming language supports XML documentation in the comments. These comments are used to describe methods and functions with their parameters. The really great thing about using these comments is that the information in them shows up when using IntelliSense. This means that someone using one of those methods will see information about the code when ever they add a call to it to their code. Visual Studio .NET 2005 adds this capability to Visual Basic .NET as well.

I tend to think that having some immediate and positive feedback on commenting in the form of things showing up in IntelliSense will help win some students over to using comments. I think it is worth a try. If any teachers reading this have thoughts on it or have used this already I would love to hear about it. Thanks!

Comments (1)

  1. NickMalik says:

    One key to teaching a concept that is not palatable, like commenting your code, is to provide early feedback on what is valuable. In this respect, the ability for Intellisense to show the method-level XML comments is an excellent support.

    The other half of this, though, is that the feedback (the tooltip) only shows up when the student USES their methods. This may not be right away depending on how the student writes their code.

    To whit, if the student writes the framework for the class, then fills in the method names (and comments) and then writes code, and then writes code that uses the class, the first opportunity to see the tooltip doesn’t appear until the end.

    On the other hand, if the student has been taught to follow Test-Driven Development principles, then the order is different. They will create a call for the method in a unit test even before they write the method. This tooltip will be empty. They will code the class interface next, immediately adding comments but no body, and compile. Step 1 in TDD is to get the code to compile and fail.

    Then they have to write the rest of the unit tests against the interface. The students will get IMMEDIATE feedback on their own comments when they see them, repeatedly, pop up even before writing the method call.

    So I would suggest that you can get a lot of bang-for-your-buck on method-level comments if you teach Test-Driven Development.

Skip to main content