Re: Danger, danger Will Robinson (documenting code)

[WebHick]

It doesn't sound like anyone had mentioned this, but I'd like to add Parental Commenting to the list. When I started learning Perl, I downloaded a program off the Internet (I learn best by example) to help. I saw things such as:

#Don't change this.
$a = '1';

#This needs to be here.  You can change it if you want
$b = '5';

and the famous:

#Set this to 1 if your system implements it.
$x = '0';

The comments make me feel like the author is telling me not to play in the street because there's "stuff" in the street. He blindly assumes that I know the "stuff" are cars and that I know the make and model of each one.

Update: Due to several complaints, removed signature

Sarah