Doug Peterson, whose blog always makes me think, had a post last week about internal documentation. Specifically things like comments which a lot of the popular block languages don’t really do that well. Of course this made me think about my code and what I teach.
The comments are great. They really let me know what is going on. That’s good because my variable names are horrible. What ever was I thinking? I’d do things a lot differently today. And in fact I do do things differently today. I have written programs like this one several times and in several different languages over the years. The variable names are much better. We’ll talk about comments in a moment.
The first time I dug out this deck of cards was some years ago when I tried to rewrite this program in Visual Basic. The comments, one in particular, was critical for me making things work. I use this as an example for my students of why they should comment their code in fact.
My most recent iteration of this program has been in TouchDevelop. I’m pleased to say my variable naming is MUCH better now. My commenting? Not so good. Part of the problem is the nature of the language. Comments are supported but somehow I never seem to think of them the same way as I do in other languages. This seems typical of block or drag and drop programming languages. (Doug brings this up which made me really think about it.)
Of course lack of commenting is not unique to drag and drop programming. Students have pointed out that some sample code I wrote and gave to them to learn from could use a lot more comments. BLUSH They are quite correct. I really need to fix that. Perhaps I’ll take on as a summer task to well document the demo code I show students. I really should be modeling what I present.
I do worry that we are losing the focus on internal documentation these days. There is this theory that well written code with well chosen variable names and identifiers should be understandable without comments. Like many theories that doesn’t seem to work as well in practice though. Well, I’m off to comment some code.
I notice my comments have gone way down compared to many years ago but it is mostly because my naming habits have changed. I can give a procedure a name that is what it does. But comments are still a big deal. Getting kids to comments is like pulling teach. I still grade heavily on comments. One of the reasons I go not spend much time in Scratch is the lack of easy commenting. When I teach Python if the kid does not do good comments and good naming I do not grade the program. Not worth my time. I try to teach the kids to write the comments first then write the code in between the comments.
ReplyDeleteYou still have your punch cards? I have moved too many times since those days. My wife is the hoarder in my family. I finally got her to throw away her 5th grade teaching mimeographs 5 years ago. She had not taught 5th grade in about 20 years. She retired last year and still wants to hang on to some of that stuff. I am having to sneak ancient math papers into the garbage can when she is not looking.