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.
Jay R. Wren 