Additional profile information on Alfred Thompson at Google+
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!
There are a couple of very useful resources for high school computer science teachers that are not as well known as they should be. If you are a high school teacher I strongly recommend them to you. If you know a high school computer science teacher, please, pass these on.
I’ll blog about more resources from time to time but these are, I think, especially good. The MSDN AA program is really wonderful for acquiring software while the community at MainFunction is just loaded with helpful resources and information. Pass it on!
Getting students (actually just about any programmer) to write comments is an uphill battle. I tried to convince my students of the value of comments by something from my own experience.
I had written a graphics program back in college many years ago. A few years later (OK about 20) I decided to write the same program again. This time I was programming in Visual Basic. FORTRAN seems not to be so easily available any more. I remembered most of the program and knew I could figure the rest out as I went alone. The program was supposed to draw geometric shapes but when I ran it lines went everywhere but where they were supposed to go. I stared at the image on the screen and realized that I’d had a similar problem when I had written the original program. What I could not remember was how I’d fixed it.
Believe it or not I still had a copy of the original code. It was on punch cards (yeah, I go back that far) and I was able to find it in a box that my wife thought I had thrown out. Fortunately I had written comments for the code. I quickly found the problem. I was passing angle information in degrees rather than in radians. A comment explaining the parameter for a function call made this clear. A quick change and the program was working just great.
That’s a good story for justifying commenting code that is non-obvious or to explain something that was not easy to understand. It’s also a good example of why interfaces to methods, modules, classes and the like should be commented. But we all know that those kinds of comments are still too rare.
I recently read a blog entry by Justin Creasy, CTO of Immerge Technologies on the subject of commenting. I recommend Justin’s version but the short version is that his team writes to comments before the code. In short they build the outline of the program using comments during the architecture and design phase of development. This has several advantages. One is that it aids the planning process. Another is that the comments are already there when the code is written. The trick of course is keeping to comments updated as the program changes.