"spir" <denis.s...@free.fr> wrote
Now what does this function do?
This is a 'what' question, namely, from a design point of view, if I
call
this function, what does it do, and what is its result-value?
What I miss is a good place for "why?". Which, when needed, is different
from "what?" and "how?". Why tells about the reason-to-be:
I always argue that comments should be for why(the code is written this
way.
what (do I do with this) should be the docstring
how (the code works) should be self evident from clearly written code
at the function lebel or in a design document for the bigger application
level how!
Those are my personal rules of thumb.
--
Alan Gauld
Author of the Learn to Program web site
http://www.alan-g.me.uk/
_______________________________________________
Tutor maillist - Tutor@python.org
http://mail.python.org/mailman/listinfo/tutor
