[Tutor] importance of Docstring

[Alan Gauld]

"spir" <denis.spir at 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/