[Tutor] commenting code well

[alan.gauld@bt.com]

> My code comments are often weak, if existent. What is good 
> practice for commenting code?

First the obligatory plug:

http://www.crosswinds.net/~agauld

in the more sequences and style sections there is guidance.

The general rule is:

Think "why" rather than "what" - explain the purpose of the 
code not how it works. The exception being where you use a 
particularly obscure algorithm or dense code. Then explain 
how and why... and of poss give a reference for the algorithm.

Normally put comments before a function and at the top of a 
file but in Python make those doc strings instead. 

Think of the audience - somebody(maybe yourself!) trying to 
understand what and how the code functions.

HTH,

Alan g