[Tutor] importance of Docstring
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
>> 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
Those are my personal rules of thumb.
Author of the Learn to Program web site
More information about the Tutor