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:

<BLOCKQUOTE><EM>
 They're something the human reader can see but the computer can't,
 and therefore are a source of misunderstanding.
</EM></BLOCKQUOTE>

 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...

<BLOCKQUOTE><EM>
 ... a skill that is at least on par with good programming skills.
 Certainly new CS students are unable to make this kind of decision.
</EM></BLOCKQUOTE>

 The thread has been a lot of fun to read.  I remain mostly of
 the view that:
<UL>
<LI> It's better to write code that says what it means and thus
     needs as few comments as  possible.  This is a skill
     students can and should work on all the time time.  </LI>
<BR/>
<LI> If the code is likely to conflict with the expectations of
     the people most likely to read your code, then add a comment.
     This part depends a lot on context and experience.  Students
     are just now earning their experience, and the context in
     which they work changes from course to course and job to 
     job.   </LI>
</UL>
 Students who care about programming, or who come to care about
 it over time, will care (or come to care) about comments, too.
-----