Most gratuitous comments

[Jean-Michel Pichavant]

----- Original Message -----
> From: sohcahtoa82 at gmail.com
> I was trying to illustrate the point that some professors would
> demand you write code like this...
> 
> # increment the line count
> lineCount += 1
> 
> # Check if line count is over 10
> if lineCount > 10
>     # Tell the user there are too many lines
>     print 'There are too many lines!
> 
> ...which is obviously bad commenting style.  But I guess my original
> minimal example was too minimal.
> 

The problem is not that every line is commented, the problem is that comments do not add any value. There's always something to tell in real life situations:

# assuming all lines look like 'v=1234\n', generate all integers provided by the user
values = (int(line.replace('v=', '')) for line in lines)

# See SPE-xxx: 10 line max do not change it
if len(lines) > 10:
  # TODO: use the logging module
  print 'There are too many lines!


In practice, this yield to a comment every 2 or 3 lines. Of course this much depend on the code itself and may vary slightly from code block to code block. Note that I am not sanctioning the use of comment on import statements :D

To go back to your point, some professors may be right when asking a comment every line, because it will be easier then for someone to back off a little bit and comment slightly less. While students with the habit of writing no comment will have much trouble commenting properly.



Cheers,

JM









-- IMPORTANT NOTICE: 

The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.