TITLE: Comments on Comments AUTHOR: Eugene Wallingford DATE: February 28, 2017 3:47 PM DESC: ----- BODY: Over the last couple of days, a thread on the SIGCSE mailing list has been revisiting the well-tilled ground of comments in code. As I told my students at the beginning of class this semester, some of my colleagues consider me a heretic for not preaching the Gospel of Comments in Code. Every context seems to have its own need for, and expectations of, comments. Wherever students end up working, both while in school and after graduation, their employers will set a standard and expect them to follow. They will figure it out. In most of my courses, I define a few minimal standard, try to set a good example in the code I give my students, and otherwise don't worry much about comments. Part of my example is that different files I give them are commented differently, depending on the context. A demo of an idea, a library to be reused in the course, and an application are different enough that they call for different kinds of comments. In a course such as compiler development, I require more documentation, both in and out of the code. Students live with that code for a semester and come to value some of their own comments many weeks later. Anyway, the SIGCSE thread included two ideas that I liked, though they came from competing sides of the argument. One asserted that comments are harmful, because:
They're something the human reader can see but the computer can't, and therefore are a source of misunderstanding.
I love the idea of thinking in terms of misunderstandings between humans and the computer. The other responded to another poster's suggestion that students be encouraged to write comments with themselves in mind: What would you like to know if you open this code six months from now? The respondent pointed out that this is unreasonable: Answering that question requires...
... a skill that is at least on par with good programming skills. Certainly new CS students are unable to make this kind of decision.
The thread has been a lot of fun to read. I remain mostly of the view that: Students who care about programming, or who come to care about it over time, will care (or come to care) about comments, too. -----