[Tutor] importance of Docstring

Alan Gauld alan.gauld at btinternet.com
Sat Apr 18 00:31:30 CEST 2009

"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 
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

More information about the Tutor mailing list