I teach at a local community college. This semester I’m teaching one of a handful of sections called “Introduction to Computer Science”. This course is supposed to be a bridge course before throwing new students directly into the typical C++ Programming course.
The thought is that some students need a little extra help before taking that first C++ course. This course is intended to give them some intermediate information and some very basic programming introduction.
Since there are other sections to this course I’ve not had to make my own course material. I’ve used PowerPoint created by others. A few times I’ve had to say things like “Just ignore that bullet, its only true from a certain point of view.”
It wasn’t until the introductory C++ slides that I blew a gasket.
After a slide on “Documentation” with these bullets:
•A well-documented program is easier to understand and modify
•You use comments to document programs
•Comments should appear in a program to:
?Explain the purpose of the program
?Identify who wrote it
?Explain the purpose of particular statements
I advanced to this slide with an example of “good” comments:
int feet; //variable to hold given feet
int inches; //variable to hold given inches
int totalInches; //variable to hold total inches
double centimeters; //variable to hold length in centimeters
At this point I lost my professionalism a bit and cursed quite a lot. I ranted about how this was useless. I feel like a channeled a little bit of everyone who I’ve heard say “comments are evil”.
When I finally got to a complete demo program instead of a code snippet, It was time for conniption.
//named constants
const int CENTIMETERS_PER_INCH = 2.54;
…
int main() {
//declare variables
int feet, inches;
…
// statements
…
For the love of programming will someone explain to me what value any of these comments have?
I can only hope that my ranting was not so extreme that students stopped listening. Hopefully they will all have a better understanding of comments and what NOT to do.
My only thing would be to say that perhaps these comments were there to reinforce the terminology used to the location of things within a sample program to people new to programming.
However, if that were true I’d think the comments would ONLY be in the sample code and not in a slide on “good” comments.
So you have my blessing to rant away.
Preach it, brother.
This is what comes of somebody being *told* comments are good, and *believing* it as a duly received dogma, without ever apparently having done enough meaningful programming of their own (and worked with the code of others) to actually know *why* and *when* they’re useful.